maquina 0.5.2 → 0.7.2

data/app/controllers/concerns/maquina/resourceful.rb

@@ -1,30 +1,92 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # The Resourceful concern provides RESTful controller actions and helper methods
+  # for Rails controllers. It implements common CRUD operations and follows
+  # Rails conventions while allowing customization of actions, attributes, and policies.
+  #
+  # Example:
+  #   class PlansController < ApplicationController
+  #     resourceful(
+  #       resource_class: Plan,
+  #       form_attributes: [{name: {type: :input}}],
+  #       list_attributes: [:name, :price],
+  #       policy_class: PlanPolicy
+  #     )
+  #   end
+  #
   module Resourceful
     extend ActiveSupport::Concern
 
+    ##
+    # Internal class to handle success/failure response blocks in dual actions
     class ResourceResponse
+      # Stores the response block
       def response(&block)
         @block = block
       end
 
+      ##
+      # Returns the stored block
       def code
         @block
       end
     end
 
     included do
+      ##
+      # The model class this controller manages
       class_attribute :resource_class, instance_writer: false
+
+      ##
+      # Optional namespace for route generation
       class_attribute :namespace, instance_writer: false
+
+      ##
+      # The parameter to use for finding resources (defaults to :id)
       class_attribute :find_by_param, instance_writer: false
+
+      ##
+      # Attributes to display in index views. It is a list of symbols.
       class_attribute :list_attributes, instance_writer: false
+
+      ##
+      # Attributes for form rendering with their configurations. It is a list of hashes.
+      # Each hash must contain a key for the attribute name and a value for the configuration.
+      # The configuration can be a hash with the following keys:
+      # - :type: The type of input to render. It can be :input, :checkbox, :textarea
+      # - :control_html: HTML attributes for the input control. It is a hash.
+      # - :input_html: HTML attributes for the input. It is a hash.
       class_attribute :form_attributes, instance_writer: false
+
+      ##
+      # Attributes to display in show views. It is a list of symbols.
       class_attribute :show_attributes, instance_writer: false
+
+      ##
+      # The ActionPolicy class for authorization
       class_attribute :policy_class, instance_writer: false
+
+      ##
+      # Whether to show the resource link in the index view
       class_attribute :show_link, instance_writer: false
 
-      attr_reader :resource, :collection
+      ##
+      # The filters to apply to the index action
+      class_attribute :filters, instance_writer: false
+
+      ##
+      # The sortable attributes for the index action
+      class_attribute :sortable, instance_writer: false
+
+      ##
+      # The current resource instance
+      attr_reader :resource
+
+      ##
+      # The resource collection for index action
+      attr_reader :collection
 
       protected
 
@@ -39,22 +101,32 @@ module Maquina
       end
 
       def base_plural_path_name
+        return nil if resource_class.nil?
         @base_plural_path_name ||= "#{namespace_path}#{resource_class.model_name.route_key}_path"
       end
 
+      ##
+      # Generates the path for a new resource
       def new_resource_path(options = {})
-        Rails.application.routes.url_helpers.send("new_#{base_singular_path_name}", **options)
+        Rails.application.routes.url_helpers.send(:"new_#{base_singular_path_name}", **options)
       end
 
+      ##
+      # Generates the edit path for a resource
       def edit_resource_path(resource, options = {})
-        Rails.application.routes.url_helpers.send("edit_#{base_singular_path_name}", resource, **options)
+        Rails.application.routes.url_helpers.send(:"edit_#{base_singular_path_name}", resource, **options)
       end
 
+      ##
+      # Generates the path for a resource
       def resource_path(resource)
         Rails.application.routes.url_helpers.send(base_singular_path_name, resource)
       end
 
+      ##
+      # Generates the collection path
       def collection_path(params = {})
+        return nil if resource_class.nil?
         Rails.application.routes.url_helpers.send(base_plural_path_name, **params)
       end
 
@@ -64,7 +136,7 @@ module Maquina
       # Controller secure params
       def resource_secure_params
         method_name = :secure_params
-        method_action_name = "#{action_name}_#{method_name}".to_sym
+        method_action_name = :"#{action_name}_#{method_name}"
 
         if respond_to?(method_action_name, true)
           send(method_action_name)
@@ -96,7 +168,7 @@ module Maquina
 
           success = ResourceResponse.new
           failure = ResourceResponse.new
-          block.call success, failure
+          yield success, failure
 
           if has_errors
             failure.code.call
@@ -108,7 +180,7 @@ module Maquina
             responded = true
 
             success = ResourceResponse.new
-            block.call success
+            yield success
 
             success.code.call
           end
@@ -118,7 +190,6 @@ module Maquina
           respond_to do |format|
             if has_errors
               format.html { render object.persisted? ? :edit : :new }
-              # format.turbo_stream
               format.json { render json: {errors: object.errors.map { |error| {error.attribute => error.message} }} }
             else
               format.html { redirect_to collection_path, status: :see_other }
@@ -138,16 +209,31 @@ module Maquina
       end
 
       helper_method :resource_class, :policy_class, :resource, :list_attributes, :form_attributes, :collection,
-        :collection_path, :resource_path, :new_resource_path, :edit_resource_path, :submit_path, :show_link
+        :collection_path, :resource_path, :new_resource_path, :edit_resource_path, :submit_path, :show_link, :filters,
+        :sortable
     end
 
     class_methods do
-      def resourceful(resource_class: nil, namespace: nil, find_by_param: :id, only: [], except: [], list_attributes: [], form_attributes: [], show_attributes: [], policy_class: nil, show_link: nil)
+      ##
+      # Configures the resourceful behavior for the controller
+      #
+      # Example:
+      #   resourceful(
+      #     resource_class: User,
+      #     list_attributes: [:email, :created_at],
+      #     policy_class: UserPolicy,
+      #     only: [:index, :show]
+      #   )
+      def resourceful(resource_class: nil, namespace: nil, find_by_param: :id, only: [], except: [],
+        list_attributes: [], form_attributes: [], show_attributes: [], policy_class: nil, show_link: nil, filters: {},
+        sortable: [])
         self.resource_class = resource_class || controller_path.classify.safe_constantize
         self.find_by_param = find_by_param || :id
         self.list_attributes = Array(list_attributes).compact
         self.form_attributes = Array(form_attributes).compact
         self.show_attributes = Array(show_attributes).compact
+        self.filters = filters
+        self.sortable = sortable
         self.policy_class = policy_class
         self.show_link = show_link
         self.namespace = namespace

data/app/controllers/maquina/application_controller.rb

@@ -13,7 +13,7 @@ module Maquina
     private
 
     def not_authorized
-      redirect_to unauthorized_path
+      redirect_to unauthorized_path, status: :see_other
     end
   end
 end

data/app/controllers/maquina/dashboard_controller.rb

@@ -2,15 +2,20 @@
 
 module Maquina
   class DashboardController < ApplicationController
-    before_action :authenticate!
-
     def index
+      if Maquina::Current.signed_in? && Maquina::Current.management?
+        @stats = [
+          {label: t("maquina.dashboard.index.stats.total_plans"), value: Maquina::Plan.count},
+          {label: t("maquina.dashboard.index.stats.total_organizations"), value: Maquina::Organization.count}
+        ]
+      end
     end
 
-    protected
+    private
 
-    def collection_path
-      nil
+    def policy_class
+      Maquina::DashboardPolicy
     end
+    helper_method :policy_class
   end
 end

data/app/controllers/maquina/invitations_controller.rb

@@ -2,8 +2,6 @@
 
 module Maquina
   class InvitationsController < ApplicationController
-    before_action :authenticate!
-
     layout false
 
     resourceful(

data/app/controllers/maquina/plans_controller.rb

@@ -2,15 +2,6 @@
 
 module Maquina
   class PlansController < ApplicationController
-    # include Maquina::Resourceful # Include this module if your ApplicationController does not include it.
-    # include Maquina::Authenticate          # Include this module if your ApplicationController does not include it.
-    before_action :authenticate!
-
-    # resource_class: Model Name
-    # form_attributes: List of attributes for edit with type
-    # list_attributes: List of attributes to display in index action
-    # show_attributes: List of attributes to display in show action
-    # policy_class: ActionPolicy class to check action authorization. Update this policy file.
     resourceful(
       resource_class: Maquina::Plan,
       form_attributes: [{name: {type: :input, control_html: {class: "sm:col-span-6"}, input_html: {class: "block w-full min-w-0 flex-1 input"}}},
@@ -18,18 +9,13 @@ module Maquina
         {price: {type: :input, control_html: {class: "sm:col-span-2"}, input_html: {class: "block w-full min-w-0 flex-1 input"}}},
         {free: {type: :checkbox, control_html: {class: "sm:col-span-6 relative flex items-start"}, input_html: {class: "check"}}},
         {active: {type: :checkbox, control_html: {class: "sm:col-span-6 relative flex items-start"}, input_html: {class: "check"}}}],
-      list_attributes: [:name, :trial, :price, :free, :active],
-      show_attributes: [:name, :trial, :price, :free, :active],
+      list_attributes: [:name, :organizations_count, :trial, :price, :free, :active, :updated_at],
       policy_class: Maquina::PlanPolicy,
+      filters: {free: {Yes: true, No: false}},
+      sortable: [:name, :price, :updated_at, :organizations_count],
       except: [:show, :destroy]
     )
 
-    def create
-      create! do |success|
-        success.response { redirect_to edit_plan_path(resource), status: :see_other }
-      end
-    end
-
     private
 
     def new_resource_path(options = {})
@@ -40,17 +26,21 @@ module Maquina
       edit_plan_path(resource, **options)
     end
 
-    def resource_path(resource)
-      plan_path(resource)
+    def resource_path(resource, options = {})
+      plan_path(resource, **options)
+    end
+
+    def collection_path(params = {})
+      plans_path(**params)
     end
 
-    def collection_path
-      plans_path
+    def before_order_by(attribute, direction)
+      attribute = :price_cents if attribute == :price
+      [attribute, direction]
     end
 
-    # Only allow a list of trusted parameters through.
     def secure_params
-      params.require(:maquina_plan).permit(:name, :trial, :price, :free, :active)
+      params.require(:plan).permit(:name, :trial, :price, :free, :active)
     end
   end
 end

data/app/controllers/maquina/sessions_controller.rb

@@ -34,7 +34,7 @@ module Maquina
       Maquina::Current.reset
 
       flash.notice = t("flash.sessions.destroy.notice")
-      redirect_to main_app.sign_in_path, status: :see_other
+      redirect_to main_app.root_path, status: :see_other
     end
 
     private

data/app/controllers/maquina/users_controller.rb

@@ -2,8 +2,6 @@
 
 module Maquina
   class UsersController < ApplicationController
-    before_action :authenticate!
-
     resourceful(
       resource_class: User,
       list_attributes: [:email, :blocked_at, :created_at],

data/app/helpers/maquina/application_helper.rb

@@ -2,14 +2,6 @@
 
 module Maquina
   module ApplicationHelper
-    def maquina_importmap_tags(entry_point = "application", importmap: Maquina.configuration.importmap)
-      safe_join [
-        javascript_inline_importmap_tag(importmap.to_json(resolver: self)),
-        javascript_importmap_module_preload_tags(importmap),
-        javascript_import_module_tag(entry_point)
-      ].compact, "\n"
-    end
-
     def class_to_form_frame(klass)
       "#{klass.to_s.underscore.tr("/", "_")}_form"
     end

data/app/helpers/maquina/navbar_menu_helper.rb

@@ -11,7 +11,7 @@ module Maquina
     end
 
     def active_menu_option?(path)
-      request.path == path
+      request.path.match?(path)
     end
 
     def profile_menu_options

data/app/models/concerns/maquina/blockeable.rb

@@ -1,6 +1,70 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # A concern that implements blocking functionality for models.
+  # Supports both permanent and temporary blocking mechanisms.
+  #
+  # == Usage
+  #
+  # Include this concern in models that need blocking capability:
+  #
+  #   class User < ApplicationRecord
+  #     include Maquina::Blockeable
+  #   end
+  #
+  # == Required Attributes
+  #
+  # Models must have one or both of:
+  # - +blocked_at+:: Timestamp for permanent blocks
+  # - +temporary_blocked_at+:: Timestamp for temporary blocks
+  #
+  # == Configuration
+  #
+  # Temporary blocking duration is controlled by:
+  # - +Maquina.configuration.temporary_block+:: Duration of temporary blocks
+  #
+  # == Special Behavior for User Model
+  #
+  # When included in Maquina::User:
+  # - Adds +memberships_blocked?+ method to check if all user's memberships are blocked
+  # - Excludes management users from membership blocking checks
+  #
+  # == Scopes
+  #
+  # === unblocked
+  #
+  # Returns records that are not blocked (either permanently or temporarily)
+  #
+  # With both blocked_at and temporary_blocked_at:
+  #   scope :unblocked, -> { where(blocked_at: nil).where("(coalesce(temporary_blocked_at + interval '? minutes', now())) <= now()", ...) }
+  #
+  # With only blocked_at:
+  #   scope :unblocked, -> { where(blocked_at: nil) }
+  #
+  # == Instance Methods
+  #
+  # === blocked?
+  #
+  # Returns true if the record is blocked by any mechanism:
+  # - Has permanent block (blocked_at present)
+  # - Has active temporary block
+  # - All memberships are blocked (User model only)
+  #
+  # === memberships_blocked?
+  #
+  # Only available for User model. Returns true if user has no active unblocked memberships.
+  #
+  # == Example
+  #
+  #   class User < ApplicationRecord
+  #     include Maquina::Blockeable
+  #   end
+  #
+  #   user.update(blocked_at: Time.current)
+  #   user.blocked? # => true
+  #   User.unblocked # => excludes blocked users
+  #
   module Blockeable
     extend ActiveSupport::Concern
 

data/app/models/concerns/maquina/organization_scoped.rb

@@ -1,6 +1,32 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # A concern that adds organization association to models.
+  #
+  # == Usage
+  #
+  # Include this concern in any model that needs to be scoped to an organization:
+  #
+  #   class MyModel < ApplicationRecord
+  #     include Maquina::OrganizationScoped
+  #   end
+  #
+  # == Associations
+  #
+  # When included, automatically adds:
+  # - +organization+:: Belongs to an Organization through maquina_organization_id foreign key
+  #
+  # == Example
+  #
+  #   class Project < ApplicationRecord
+  #     include Maquina::OrganizationScoped
+  #     # Project now has organization association
+  #   end
+  #
+  #   project = Project.create(organization: current_organization)
+  #   project.organization # => returns associated Maquina::Organization
+  #
   module OrganizationScoped
     extend ActiveSupport::Concern
 

data/app/models/concerns/maquina/retain_passwords.rb

@@ -1,6 +1,43 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # A concern that implements password history and reuse prevention.
+  #
+  # == Usage
+  #
+  # Include this concern in models that need password history tracking:
+  #
+  #   class User < ApplicationRecord
+  #     include Maquina::RetainPasswords
+  #   end
+  #
+  # == Configuration
+  #
+  # Password retention behavior is controlled by:
+  # - +Maquina.configuration.password_retain_count+:: Number of previous passwords to retain
+  #
+  # == Callbacks
+  #
+  # When included, automatically adds:
+  # - Validation to prevent password reuse
+  # - After create: Stores initial password in history
+  # - After update: Stores new password in history when password changes
+  #
+  # == Validations
+  #
+  # - +password+:: Must not match any previously used passwords within retention limit
+  #
+  # == Example
+  #
+  #   class User < ApplicationRecord
+  #     include Maquina::RetainPasswords
+  #     has_secure_password
+  #   end
+  #
+  #   user.update(password: 'old_password') # Stored in history
+  #   user.update(password: 'old_password') # Validation error: password already used
+  #
   module RetainPasswords
     extend ActiveSupport::Concern
 
@@ -11,6 +48,10 @@ module Maquina
 
       private
 
+      # Validates that the new password hasn't been used before
+      #
+      # Compares the new password against stored password history
+      # Adds error if password was previously used within retention limit
       def password_uniqueness
         return if Maquina.configuration.password_retain_count.blank? || Maquina.configuration.password_retain_count.zero?
 
@@ -24,6 +65,9 @@ module Maquina
         errors.add(:password, :password_already_used) if used_before.present?
       end
 
+      # Stores the current password digest in password history
+      #
+      # Delegates to UsedPassword to handle storage and history maintenance
       def store_password_digest
         Maquina::UsedPassword.store_password_digest(id, password_digest)
       end

data/app/models/concerns/maquina/sqlite_search.rb

@@ -0,0 +1,92 @@
+module Maquina
+  module SqliteSearch
+    extend ActiveSupport::Concern
+
+    private def update_search_index
+      primary_key = self.class.primary_key
+      table_name = self.class.table_name
+      foreign_key = self.class.to_s.foreign_key
+
+      search_attrs = @@search_scope_attrs.each_with_object({}) { |attr, acc|
+        acc[attr] = quote_string(send(attr) || "")
+      }
+      id_value = attributes[primary_key]
+
+      sql_delete = <<~SQL.strip
+        DELETE FROM fts_#{table_name} WHERE #{foreign_key} = #{id_value};
+      SQL
+      self.class.connection.execute(sql_delete)
+
+      sql_insert = <<~SQL.strip
+        INSERT INTO fts_#{table_name}(#{search_attrs.keys.join(", ")}, #{foreign_key})
+        VALUES (#{search_attrs.values.map { |value| "'#{value}'" }.join(", ")}, #{attributes[primary_key]});
+      SQL
+      self.class.connection.execute(sql_insert)
+    end
+
+    private def delete_search_index
+      primary_key = self.class.primary_key
+      table_name = self.class.table_name
+      foreign_key = self.class.to_s.foreign_key
+      id_value = attributes[primary_key]
+
+      sql_delete = <<~SQL.strip
+        DELETE FROM fts_#{table_name} WHERE #{foreign_key} = #{id_value};
+      SQL
+      self.class.connection.execute(sql_delete)
+    end
+
+    included do
+      after_save_commit :update_search_index
+      after_destroy_commit :delete_search_index
+
+      scope_foreign_key = to_s.foreign_key
+      scope :full_search, ->(query) {
+        return none if query.blank?
+
+        sql = <<~SQL.strip
+          SELECT #{scope_foreign_key} AS id FROM fts_#{table_name}
+          WHERE fts_#{table_name} = '#{query}' ORDER BY rank;
+        SQL
+        ids = connection.execute(sql).map(&:values).flatten
+        where(id: ids)
+      }
+    end
+
+    class_methods do
+      def search_scope(*attrs)
+        @@search_scope_attrs = attrs
+      end
+
+      def rebuild_search_index(*ids)
+        target_ids = Array(ids)
+        target_ids = self.ids if target_ids.empty?
+
+        scope_foreign_key = to_s.foreign_key
+
+        delete_where = Array(ids).any? ? "WHERE #{scope_foreign_key} IN (#{ids.join(", ")})" : ""
+        sql_delete = <<~SQL.strip
+          DELETE FROM fts_#{table_name} #{delete_where};
+        SQL
+        connection.execute(sql_delete)
+
+        target_ids.each do |id|
+          record = where(id: id).pluck(*@@search_scope_attrs, :id).first
+          if record.present?
+            id = record.pop
+
+            sql_insert = <<~SQL.strip
+              INSERT INTO fts_#{table_name}(#{@@search_scope_attrs.join(", ")}, #{scope_foreign_key})
+              VALUES (#{record.map { |value| "'#{quote_string(value)}'" }.join(", ")}, #{id});
+            SQL
+            connection.execute(sql_insert)
+          end
+        end
+      end
+
+      def quote_string(s)
+        s.gsub("\\", '\&\&').gsub("'", "''")
+      end
+    end
+  end
+end

data/app/models/concerns/maquina/user_scoped.rb

@@ -1,6 +1,32 @@
 # frozen_string_literal: true
 
 module Maquina
+  ##
+  # A concern that adds user association to models.
+  #
+  # == Usage
+  #
+  # Include this concern in any model that needs to be scoped to a user:
+  #
+  #   class MyModel < ApplicationRecord
+  #     include Maquina::UserScoped
+  #   end
+  #
+  # == Associations
+  #
+  # When included, automatically adds:
+  # - +user+:: Belongs to a User through maquina_user_id foreign key
+  #
+  # == Example
+  #
+  #   class Document < ApplicationRecord
+  #     include Maquina::UserScoped
+  #     # Document now has user association
+  #   end
+  #
+  #   document = Document.create(user: current_user)
+  #   document.user # => returns associated Maquina::User
+  #
   module UserScoped
     extend ActiveSupport::Concern