feature_pack 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c48de284c1d9224798b073645f3a80e923d4e72445272641f644e8ed15bb6bf
-  data.tar.gz: 9c8c489303a5f0a878c756abbc6abb03b8c6073e3cb8a1beda43eeaba0705365
+  metadata.gz: 4ad6b0b7d1fef825b25714c0b54b468935b5d30bbb45b1e1cdaa2f7023417345
+  data.tar.gz: 795e0c96835d48091f3e50f0d37add2cd0b0a459a65fc592c2be527550ac3519
 SHA512:
-  metadata.gz: 76ac5cdd3bcb0a241cbc40cd12ad11edbf94e267142e5d2a0e30e26a4b71462c9ae2cc58f0244034ec8d862d7ae8a67f70047273540eab4592e195e6085ca7fe
-  data.tar.gz: f021bce17beadad88f4501768d2021e65e2393db17cd625053ad51e0cfff334555041d055c867517317f52cf79f78b647fe1fa38620f0427c112f8184094e6c1
+  metadata.gz: 0cfcaddc9bdb103bafa8be27d9c24d6034455660cac7077d58f11abf7faf095f705869fa534ded2efa02aa574f52437d871eae361c877fa6a0ab35c7ed7de51e
+  data.tar.gz: 7bc13892f86bb7f7b720da3aa79bcdc85e482fbaa2b1e3489d96947145dd773e725dd0e170257d2e6f42c775126267313e4095089fbc4e0af691a8e206eb541d

data/README.md

@@ -152,6 +152,31 @@ class FeaturePack::HumanResources::EmployeesController < FeaturePack::HumanResou
 end
 ```
 
+Generated feature controllers inherit their group's controller, so group callbacks
+(authentication, authorization, etc.) apply to every feature. The setup callback
+resolves the context from the routed path (`feature_pack/<group>/<feature>`): when the
+second segment is a registered feature the request receives `@group` and `@feature` and
+uses the feature's views; otherwise it receives `@group` and the group's views. No
+extra declaration is needed in feature controllers.
+
+Feature controllers that don't need a group controller can still inherit
+`FeaturePack::Controller`, which requires the path to name a registered feature.
+
+The private hooks `set_view_lookup_context_prefix` and `set_layout_paths` can be
+overridden in a group controller and apply to both group and feature requests.
+
+#### Migrating from 0.10.x
+
+- To share group callbacks, change a feature controller's superclass from
+  `FeaturePack::Controller` to `FeaturePack::<Group>Controller`.
+- `__after_initialize.rb` hooks are no longer loaded. Move that code to a Rails
+  initializer or to the group/feature controller and delete the hook files. Leftover
+  files are ignored by Zeitwerk, but they are dead code.
+- `FeaturePack::API::Controller` was removed; inherit `ActionController::API` directly.
+- `FeaturePack.setup` now fails when `app/feature_packs` does not exist. Create the
+  directory, or call `FeaturePack.setup(require_features_path: false)` to boot with no
+  groups (a warning is logged).
+
 ## Routes
 
 Routes are automatically configured based on manifest files:
@@ -247,68 +272,6 @@ Access aliased constants:
 @feature.service       # => FeaturePack::HumanResources::Employees::EmployeeService
 ```
 
-## Hooks
-
-### after_initialize Hook
-
-O FeaturePack suporta hooks `after_initialize` que permitem executar código customizado após o carregamento de grupos e features.
-
-#### Como Funciona
-
-Durante o processo de setup do FeaturePack, após todos os grupos e features serem descobertos e configurados, o sistema procura e executa arquivos `__after_initialize.rb` específicos.
-
-#### Localização dos Arquivos
-
-- **Para grupos**: `app/feature_packs/[nome_do_grupo]/_group_space/__after_initialize.rb`
-- **Para features**: `app/feature_packs/[nome_do_grupo]/[nome_da_feature]/__after_initialize.rb`
-
-#### Contexto de Execução
-
-Os arquivos `__after_initialize.rb` são executados no contexto do objeto group ou feature, permitindo acesso direto a todas as suas propriedades através de `self`.
-
-#### Exemplos de Uso
-
-**Hook para grupo:**
-```ruby
-# app/feature_packs/group_241209_human_resources/_group_space/__after_initialize.rb
-
-# Registrar o grupo em um sistema de auditoria
-Rails.logger.info "Grupo #{name} carregado com #{features.size} features"
-
-# Configurar permissões globais do grupo
-features.each do |feature|
-  Rails.logger.info "  - Feature #{feature.name} disponível em #{feature.manifest[:url]}"
-end
-
-# Carregar configurações específicas do grupo
-config_file = File.join(absolute_path, '_group_space', 'config.yml')
-if File.exist?(config_file)
-  @config = YAML.load_file(config_file)
-end
-```
-
-**Hook para feature:**
-```ruby
-# app/feature_packs/group_241209_human_resources/feature_241209_employees/__after_initialize.rb
-
-# Registrar rotas dinâmicas
-Rails.logger.info "Feature #{name} inicializada no grupo #{group.name}"
-
-# Verificar dependências
-required_gems = %w[devise cancancan]
-required_gems.each do |gem_name|
-  unless Gem.loaded_specs.key?(gem_name)
-    Rails.logger.warn "Feature #{name} requer a gem #{gem_name}"
-  end
-end
-
-# Registrar a feature em um sistema de métricas
-StatsD.increment("features.#{group.name}.#{name}.loaded") if defined?(StatsD)
-
-# Configurar cache específico da feature
-Rails.cache.write("feature:#{group.name}:#{name}:loaded_at", Time.current)
-```
-
 ## Best Practices
 
 1. **Group Organization**: Group related features that share common functionality
@@ -356,4 +319,14 @@ Gedean Dias - gedean.dias@gmail.com
 
 - [GitHub Repository](https://github.com/gedean/feature_pack)
 - [RubyGems](https://rubygems.org/gems/feature_pack)
-- [Bug Reports](https://github.com/gedean/feature_pack/issues)
+- [Bug Reports](https://github.com/gedean/feature_pack/issues)
+
+## Tests
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+The suite covers discovery, setup rollback, first-time generation, duplicate
+protection, inherited authorization, and Rails request rendering using ERB fixtures.

data/doc/feature_pack.md

@@ -30,7 +30,7 @@ The module defines several read-only attributes:
 
 The `setup` method initializes the FeaturePack library:
 
-1. Validates the provided `features_path`
+1. Resolves `features_path` to `Rails.root/app/feature_packs` and validates it (missing directory raises unless `require_features_path: false`)
 2. Sets up ignored paths
 3. Discovers and initializes groups and features
 4. Sets up routes and controllers for groups and features
@@ -38,7 +38,7 @@ The `setup` method initializes the FeaturePack library:
 ### Usage
 
 ```ruby
-FeaturePack.setup(features_path: '/path/to/features')
+FeaturePack.setup
 ```
 
 ## Groups

data/lib/feature_pack/controller.rb

@@ -1,62 +1,9 @@
-# Base controller for all feature controllers
-# Handles the setup of features, views, and layouts
+require_relative 'feature_controller_setup'
+
+# Base controller for features without a custom group controller.
 class FeaturePack::Controller < ApplicationController
+  include FeaturePack::FeatureControllerSetup
   prepend_before_action :setup_feature
 
-  # Default index action
   def index; end
-
-  private
-
-  # Main setup method that configures the feature environment
-  def setup_feature
-    set_group_and_feature
-    set_view_lookup_context_prefix
-    set_layout_paths
-  end
-
-  # Extracts and sets the group and feature from the controller path
-  def set_group_and_feature
-    group_name, feature_name = params['controller']
-      .delete_prefix('feature_pack/')
-      .split('/')
-      .map(&:to_sym)
-    
-    @group = FeaturePack.group(group_name)
-    @feature = FeaturePack.feature(group_name, feature_name)
-    
-    raise FeaturePack::Error::NoGroup, "Group '#{group_name}' not found" if @group.nil?
-    raise FeaturePack::Error::NoDataError, "Feature '#{feature_name}' not found in group '#{group_name}'" if @feature.nil?
-  end
-
-  # Configures the view lookup path to include feature-specific views
-  def set_view_lookup_context_prefix
-    return if lookup_context.prefixes.include?(@feature.views_relative_path)
-
-    lookup_context.prefixes.prepend(@feature.views_relative_path)
-  end
-
-  # Sets up header and footer layout paths with fallback logic
-  # Search order:
-  # 1. Feature-specific partials
-  # 2. Group-level partials (fallback)
-  # 3. Application default (if neither exists)
-  def set_layout_paths
-    feature_partials_path = @feature.views_relative_path.join('partials')
-    group_partials_path = @feature.group.views_path.concat('/partials')
-
-    # Set header layout
-    if template_exists?('header', feature_partials_path, true)
-      @header_layout_path = @feature.view('partials/header')
-    elsif template_exists?('header', group_partials_path, true)
-      @header_layout_path = @feature.group.view('partials/header')
-    end
-
-    # Set footer layout
-    if template_exists?('footer', feature_partials_path, true)
-      @footer_layout_path = @feature.view('partials/footer')
-    elsif template_exists?('footer', group_partials_path, true)
-      @footer_layout_path = @feature.group.view('partials/footer')
-    end
-  end
 end

data/lib/feature_pack/feature_controller_setup.rb

@@ -0,0 +1,111 @@
+require_relative '../feature_pack'
+
+# Request setup shared by group controllers, feature controllers that inherit
+# their group controller, and standalone feature controllers
+# (FeaturePack::Controller).
+#
+# The group and feature are resolved from the routed controller path
+# ("feature_pack/<group>[/<feature>]"). When the second segment names a
+# registered feature the request gets feature context (@group and @feature);
+# otherwise it gets group context (@group only). No opt-in is required, so a
+# controller can never silently receive the wrong setup.
+module FeaturePack::FeatureControllerSetup
+  ROUTE_NAMESPACE = 'feature_pack/'.freeze
+  PROTECTED_IVARS = %i[@_feature_pack_prefixes].freeze
+
+  # Implicit rendering and the lookup context both read `_prefixes`.
+  # Override it per instance so a request-specific prefix never leaks into the
+  # controller class' memoized array (which subclasses share by reference).
+  def _prefixes
+    @_feature_pack_prefixes || super
+  end
+
+  # Keep the internal prefix array out of view assigns
+  def _protected_ivars
+    super + PROTECTED_IVARS
+  end
+
+  private
+
+  # Resolves group and feature from the route and configures the request.
+  # Used by GroupController (and everything inheriting it).
+  def setup_feature_pack_context
+    group_name, feature_name = feature_pack_route_segments
+    set_group(group_name)
+    @feature = @group.feature(feature_name) if feature_name
+
+    set_view_lookup_context_prefix
+    set_layout_paths
+  end
+
+  # Configures a request that must resolve to a feature (FeaturePack::Controller).
+  def setup_feature
+    set_group_and_feature
+    set_view_lookup_context_prefix
+    set_layout_paths
+  end
+
+  # @return [Array<Symbol>] [group_name, feature_name]; feature_name may be nil
+  def feature_pack_route_segments
+    path = (params[:controller] || controller_path).to_s
+    path.delete_prefix(ROUTE_NAMESPACE).split('/').first(2).map(&:to_sym)
+  end
+
+  def set_group(group_name)
+    @group = FeaturePack.group(group_name)
+    raise FeaturePack::Error::NoGroup, "Group '#{group_name}' not found" if @group.nil?
+  end
+
+  # Extracts and sets the group and feature from the controller path
+  def set_group_and_feature
+    group_name, feature_name = feature_pack_route_segments
+    set_group(group_name)
+
+    @feature = @group.feature(feature_name)
+    return unless @feature.nil?
+
+    raise FeaturePack::Error::NoDataError, "Feature '#{feature_name}' not found in group '#{group_name}'"
+  end
+
+  # Configures the view lookup path to include feature (or group) views.
+  # Overridable in group controllers; applies to group and feature requests.
+  def set_view_lookup_context_prefix
+    prepend_view_prefix(@feature ? @feature.views_relative_path : @group.views_path)
+  end
+
+  # Sets up header and footer layout paths with fallback logic
+  # Search order:
+  # 1. Feature-specific partials (feature requests only)
+  # 2. Group-level partials
+  # 3. Application default (if neither exists)
+  def set_layout_paths
+    @header_layout_path = resolve_layout_partial('header')
+    @footer_layout_path = resolve_layout_partial('footer')
+  end
+
+  def prepend_view_prefix(prefix)
+    prefix = prefix.to_s
+    return if _prefixes.include?(prefix)
+
+    @_feature_pack_prefixes = [prefix, *_prefixes].freeze
+    lookup_context.prefixes = @_feature_pack_prefixes if defined?(@_lookup_context) && @_lookup_context
+  end
+
+  # @return [String, nil] the view path of the first existing partial
+  def resolve_layout_partial(name)
+    layout_partial_candidates.each do |partials_prefix, view_path|
+      return format(view_path, name) if template_exists?(name, partials_prefix, true)
+    end
+    nil
+  end
+
+  # @return [Array<Array(String, String)>] pairs of [partials_prefix, view path format with %s for the name]
+  def layout_partial_candidates
+    candidates = []
+    if @feature
+      candidates << [@feature.views_relative_path.join('partials').to_s, @feature.view('partials/%s')]
+    end
+    candidates << ["#{@group.views_path}/partials", @group.view('partials/%s')]
+    candidates
+  end
+end

data/lib/feature_pack/group_controller.rb

@@ -1,45 +1,15 @@
-# Base controller for all group controllers
-# Handles the setup of groups and their views
+require_relative 'feature_controller_setup'
+
+# Base controller for all group controllers.
+#
+# Feature controllers inherit their group controller, so group callbacks
+# (authentication, authorization...) apply to every feature. The setup callback
+# resolves group or feature context from the route, so no extra declaration is
+# needed in feature controllers.
 class FeaturePack::GroupController < ApplicationController
-  prepend_before_action :setup_group
-  
+  include FeaturePack::FeatureControllerSetup
+  prepend_before_action :setup_feature_pack_context
+
   # Default index action
   def index; end
-
-  private
-
-  # Main setup method that configures the group environment
-  def setup_group
-    set_group
-    set_view_lookup_context_prefix
-    set_layout_paths
-  end
-
-  # Extracts and sets the group from the controller path
-  def set_group
-    group_name = params[:controller].split('/')[1].to_sym
-    @group = FeaturePack.group(group_name)
-    
-    raise FeaturePack::Error::NoGroup, "Group '#{group_name}' not found" if @group.nil?
-  end
-
-  # Configures the view lookup path to include group-specific views
-  def set_view_lookup_context_prefix
-    return if lookup_context.prefixes.include?(@group.views_path)
-
-    lookup_context.prefixes.prepend(@group.views_path)
-  end
-
-  # Sets up header and footer layout paths for the group
-  def set_layout_paths
-    partials_path = @group.views_path.concat('/partials')
-
-    if template_exists?('header', partials_path, true)
-      @header_layout_path = @group.view('partials/header')
-    end
-
-    if template_exists?('footer', partials_path, true)
-      @footer_layout_path = @group.view('partials/footer')
-    end
-  end
 end

data/lib/feature_pack.rb

@@ -1,8 +1,14 @@
 require 'active_support/all'
+require 'ostruct'
 
 # FeaturePack module provides a way to organize Rails applications into
 # groups and features, enabling better code organization and isolation
 module FeaturePack
+  @initialized = false
+
+  # Raised when registry data is requested before `setup` succeeded
+  class NotInitializedError < StandardError; end
+
   # Pattern constants for identifying groups and features
   GROUP_ID_PATTERN = /^group_.*?_/.freeze
   FEATURE_ID_PATTERN = /^feature_.*?_/.freeze
@@ -11,9 +17,10 @@ module FeaturePack
   GROUP_SPACE_DIRECTORY = '_group_space'.freeze
   MANIFEST_FILE_NAME = 'manifest.yaml'.freeze
   CONTROLLER_FILE_NAME = 'controller.rb'.freeze
-  AFTER_INITIALIZE_FILE_NAME = '__after_initialize.rb'.freeze
+  # Hook file from 0.10.x; no longer loaded but still kept away from Zeitwerk
+  LEGACY_HOOK_FILE_NAME = '__after_initialize.rb'.freeze
 
-  # Attribute readers that will be dynamically defined
+  # Registry attributes populated by `setup`
   ATTR_READERS = %i[
     path
     features_path
@@ -27,20 +34,39 @@ module FeaturePack
   class << self
     # Sets up the FeaturePack system
     # This method should be called once during Rails initialization
-    def setup
-      raise 'FeaturePack already setup!' if defined?(@@setup_executed_flag)
-
-      initialize_paths
-      load_dependencies
-      discover_groups
-      discover_features
-      finalize_setup
+    # @param require_features_path [Boolean] when true (default), a missing
+    #   app/feature_packs directory aborts the boot; pass false to boot with no
+    #   groups (e.g. before generating the first group).
+    def setup(require_features_path: true)
+      raise 'FeaturePack already setup!' if @initialized
+
+      begin
+        initialize_paths(require_features_path)
+        load_dependencies
+        discover_groups
+        discover_features
+        finalize_setup
+        @initialized = true
+      rescue StandardError, ScriptError
+        # ScriptError covers LoadError/SyntaxError raised while loading files.
+        reset_state!
+        raise
+      end
+    end
+
+    def initialized? = @initialized
+
+    ATTR_READERS.each do |attr|
+      define_method(attr) do
+        ensure_initialized!
+        instance_variable_get("@#{attr}")
+      end
     end
 
     # Finds a group by name
     # @param group_name [Symbol] The name of the group
     # @return [OpenStruct, nil] The group object or nil if not found
-    def group(group_name) = @@groups.find { it.name.eql?(group_name) }
+    def group(group_name) = groups.find { |group| group.name.eql?(group_name) }
 
     # Finds a feature within a group
     # @param group_name [Symbol] The name of the group
@@ -49,45 +75,68 @@ module FeaturePack
     def feature(group_name, feature_name)
       requested_group = group(group_name)
       return nil if requested_group.nil?
-      
+
       requested_group.feature(feature_name)
     end
 
     private
 
-    def initialize_paths
-      @@path = Pathname.new(__dir__)
-      @@features_path = Pathname.new(Rails.root.join('app/feature_packs'))
-      
-      validate_features_path!
-      
-      @@groups_controllers_paths = []
-      @@features_controllers_paths = []
-      @@ignored_paths = Dir.glob("#{@@features_path}/[!]*/")
-      @@javascript_files_paths = discover_javascript_files
+    def ensure_initialized!
+      return if @initialized
+
+      raise NotInitializedError, 'FeaturePack is not set up. Call FeaturePack.setup first.'
+    end
+
+    def initialize_paths(require_features_path)
+      @path = Pathname.new(__dir__)
+      @features_path = Pathname.new(Rails.root.join('app/feature_packs'))
+
+      validate_features_path!(require_features_path)
+
+      @groups_controllers_paths = []
+      @features_controllers_paths = []
+      # Every entry under features_path is ignored by Zeitwerk; controllers and
+      # routes are loaded explicitly (see SETUP.md), and feature modules are
+      # registered through push_dir by the host application.
+      @ignored_paths = Dir.glob("#{@features_path}/*/")
+      @javascript_files_paths = discover_javascript_files
     end
 
-    def load_dependencies = load @@path.join('feature_pack/error.rb')
+    def load_dependencies = load(@path.join('feature_pack/error.rb'))
+
+    def validate_features_path!(require_features_path)
+      if @features_path.exist?
+        raise "Features path is not a directory: '#{@features_path}'" unless @features_path.directory?
+        return
+      end
+
+      message = "Features path '#{@features_path}' does not exist"
+      if require_features_path
+        raise "#{message}. Create app/feature_packs or call FeaturePack.setup(require_features_path: false)"
+      end
+
+      log_warning("[FeaturePack] #{message}. No groups or features will be loaded.")
+    end
 
-    def validate_features_path!
-      raise "Invalid features_path: '#{@@features_path}'" if @@features_path.nil?
-      raise "Features path does not exist: '#{@@features_path}'" unless Dir.exist?(@@features_path)
+    def log_warning(message)
+      logger = Rails.respond_to?(:logger) ? Rails.logger : nil
+      logger ? logger.warn(message) : warn(message)
     end
 
     def discover_javascript_files
-      Dir.glob("#{@@features_path}/[!_]*/**/*.js")
-        .map { |js_path| js_path.sub(/^#{Regexp.escape(@@features_path.to_s)}\//, '') }
-        .to_a
+      prefix = "#{@features_path}/"
+      Dir.glob("#{prefix}[!_]*/**/*.js").map { |js_path| js_path.delete_prefix(prefix) }
     end
 
-    def finalize_setup
-      ATTR_READERS.each { |attr| define_singleton_method(attr) { class_variable_get("@@#{attr}") } }
-      @@ignored_paths << @@path.join('feature_pack/feature_pack_routes.rb')
-      execute_after_initialize_hooks
-      @@setup_executed_flag = true
+    def finalize_setup = @ignored_paths << @path.join('feature_pack/feature_pack_routes.rb')
+
+    # Clears every registry attribute so a failed or repeated setup starts clean
+    def reset_state!
+      @initialized = false
+      ATTR_READERS.each { |attr| remove_instance_variable("@#{attr}") if instance_variable_defined?("@#{attr}") }
     end
 
-    def discover_groups = @@groups = Dir.glob("#{@@features_path}/[!_]*/").map { build_group(it) }
+    def discover_groups = @groups = Dir.glob("#{@features_path}/[!_]*/").map { |group_path| build_group(group_path) }
 
     def build_group(group_path)
       relative_path = Pathname.new(group_path)
@@ -96,7 +145,7 @@ module FeaturePack
       validate_group_id!(base_path)
       
       routes_file = find_group_routes_file(group_path, base_path)
-      @@groups_controllers_paths << File.join(group_path, GROUP_SPACE_DIRECTORY, CONTROLLER_FILE_NAME)
+      register_group_controller(group_path)
       
       group = create_group_struct(base_path, group_path, relative_path, routes_file)
       setup_group_aliases(group)
@@ -111,6 +160,14 @@ module FeaturePack
       end
     end
 
+    # Groups without a controller are allowed (namespace-only groups);
+    # add_feature validates the controller when a feature needs to inherit it.
+    def register_group_controller(group_path)
+      controller_path = File.join(group_path, GROUP_SPACE_DIRECTORY, CONTROLLER_FILE_NAME)
+      @groups_controllers_paths << controller_path if File.exist?(controller_path)
+      @ignored_paths << File.join(group_path, GROUP_SPACE_DIRECTORY, LEGACY_HOOK_FILE_NAME)
+    end
+
     def find_group_routes_file(group_path, base_path)
       routes_path = File.join(group_path, GROUP_SPACE_DIRECTORY, 'routes.rb')
       File.exist?(routes_path) ? File.join(base_path, GROUP_SPACE_DIRECTORY, 'routes') : nil
@@ -126,7 +183,7 @@ module FeaturePack
       OpenStruct.new(
         id: base_path.scan(GROUP_ID_PATTERN).first.delete_suffix('_'),
         name: base_path.gsub(GROUP_ID_PATTERN, '').to_sym,
-        metadata_path: @@features_path.join(group_path, GROUP_SPACE_DIRECTORY),
+        metadata_path: @features_path.join(group_path, GROUP_SPACE_DIRECTORY),
         relative_path: relative_path,
         base_dir: File.basename(relative_path, File::SEPARATOR),
         routes_file: routes_file,
@@ -142,8 +199,8 @@ module FeaturePack
     end
 
     def setup_group_aliases(group)
-      group.manifest.fetch(:const_aliases, []).each do
-        alias_method_name, alias_const_name = it.first
+      group.manifest.fetch(:const_aliases, []).each do |const_alias|
+        alias_method_name, alias_const_name = const_alias.first
         group.define_singleton_method(alias_method_name) do
           "FeaturePack::#{group.name.to_s.camelize}::#{alias_const_name}".constantize
         end
@@ -151,14 +208,14 @@ module FeaturePack
     end
 
     def define_group_methods(group)
-      def group.feature(feature_name) = features.find { it.name.eql?(feature_name) }      
+      def group.feature(feature_name) = features.find { |feature| feature.name.eql?(feature_name) }
       def group.views_path = "#{base_dir}/#{GROUP_SPACE_DIRECTORY}/views"
       def group.view(view_name) = "#{base_dir}/#{GROUP_SPACE_DIRECTORY}/views/#{view_name}"     
       def group.javascript_module(javascript_file_name) = "#{base_dir}/#{GROUP_SPACE_DIRECTORY}/javascript/#{javascript_file_name}"
     end
 
     def discover_features
-      @@groups.each do |group|
+      @groups.each do |group|
         Dir.glob("#{group.relative_path}[!_]*/").each do |feature_path|
           build_feature(group, feature_path)
         end
@@ -166,7 +223,7 @@ module FeaturePack
     end
 
     def build_feature(group, feature_path)
-      absolute_path = @@features_path.join(feature_path)
+      absolute_path = @features_path.join(feature_path)
       relative_path = Pathname.new(feature_path)
       base_path = File.basename(feature_path, File::SEPARATOR)
       
@@ -188,20 +245,6 @@ module FeaturePack
       group.features << feature
     end
 
-    def execute_after_initialize_hooks
-      # Executar hooks dos grupos
-      @@groups.each do |group|
-        hook_file = File.join(group.metadata_path, AFTER_INITIALIZE_FILE_NAME)
-        group.instance_eval(File.read(hook_file), hook_file) if File.exist?(hook_file)
-
-        # Executar hooks das features
-        group.features.each do |feature|
-          hook_file = File.join(feature.absolute_path, AFTER_INITIALIZE_FILE_NAME)
-          feature.instance_eval(File.read(hook_file), hook_file) if File.exist?(hook_file)
-        end
-      end
-    end
-
     def validate_feature_id!(base_path, relative_path)
       if base_path.scan(FEATURE_ID_PATTERN).empty?
         raise "Feature '#{relative_path}' does not have a valid ID. Expected format: feature_<id>_<name>"
@@ -209,20 +252,20 @@ module FeaturePack
     end
 
     def setup_feature_paths(relative_path, routes_file_path)
-      # Handled after initialize hooks
-      @@ignored_paths << File.join(relative_path, AFTER_INITIALIZE_FILE_NAME)
-
       # Custom routes file loads before Rails default routes
-      @@ignored_paths << routes_file_path
+      @ignored_paths << routes_file_path
       
       # Controllers have special load process due to Zeitwerk
       controller_path = relative_path.join(CONTROLLER_FILE_NAME)
-      @@features_controllers_paths << controller_path
-      @@ignored_paths << controller_path
+      @features_controllers_paths << controller_path
+      @ignored_paths << controller_path
+      # Feature directories are Zeitwerk roots (push_dir), so the group-level
+      # ignore does not cover leftover 0.10.x hook files.
+      @ignored_paths << relative_path.join(LEGACY_HOOK_FILE_NAME)
     end
 
     def create_feature_struct(base_path, feature_name, group, absolute_path, relative_path, routes_file_path, feature_path)
-      feature_sub_path = relative_path.sub(/^#{Regexp.escape(@@features_path.to_s)}\//, '')
+      feature_sub_path = relative_path.sub(/^#{Regexp.escape(@features_path.to_s)}\//, '')
       manifest_path = File.join(feature_path, MANIFEST_FILE_NAME)
       
       unless File.exist?(manifest_path)
@@ -239,8 +282,8 @@ module FeaturePack
         routes_file_path: routes_file_path,
         routes_file: feature_sub_path.join('routes'),
         views_absolute_path: absolute_path.join('views'),
-        views_relative_path: relative_path.sub(/^#{Regexp.escape(@@features_path.to_s)}\//, '').join('views'),
-        javascript_relative_path: relative_path.sub(/^#{Regexp.escape(@@features_path.to_s)}\//, '').join('javascript'),
+        views_relative_path: feature_sub_path.join('views'),
+        javascript_relative_path: feature_sub_path.join('javascript'),
         manifest: load_manifest(manifest_path)
       )
     end
@@ -253,8 +296,8 @@ module FeaturePack
     end
 
     def setup_feature_aliases(feature)
-      feature.manifest.fetch(:const_aliases, []).each do
-        alias_method_name, alias_const_name = it.first
+      feature.manifest.fetch(:const_aliases, []).each do |const_alias|
+        alias_method_name, alias_const_name = const_alias.first
         feature.define_singleton_method(alias_method_name) do
           "#{class_name}::#{alias_const_name}".constantize
         end

data/lib/generators/feature_pack/add_feature/add_feature_generator.rb

@@ -8,13 +8,15 @@ module FeaturePack
     desc 'Creates a new Feature within an existing Group'
     source_root File.expand_path('templates', __dir__)
 
-    argument :name, type: :string, required: true, desc: 'The group/feature name (snake_case) format: group_name/feature_name'
+    argument :name, type: :string, required: true,
+                    desc: 'The group/feature name (snake_case) format: group_name/feature_name'
 
     def add_feature
       validate_feature_name!
       parse_names
       check_group_existence!
       check_feature_existence!
+      check_group_controller!
       
       @feature_id = generate_feature_id
       @feature_dir = @group.relative_path.join("feature_#{@feature_id}_#{@feature_name}")
@@ -36,8 +38,8 @@ module FeaturePack
     def parse_names
       @group_name, @feature_name = name.split('/')
       
-      unless @group_name.match?(/^[a-z][a-z0-9_]*$/) && @feature_name.match?(/^[a-z][a-z0-9_]*$/)
-        raise Thor::Error, "Group and feature names must be in snake_case format (lowercase letters, numbers, and underscores, starting with a letter)"
+      unless @group_name.match?(/^[a-z_]+$/) && @feature_name.match?(/^[a-z_]+$/)
+        raise Thor::Error, "Group and feature names must be in snake_case format"
       end
       
       @group_class_name = @group_name.camelcase
@@ -52,6 +54,31 @@ module FeaturePack
       end
     end
 
+    # The generated feature controller inherits FeaturePack::<Group>Controller,
+    # so validate the resolved class independently of its declaration syntax.
+    def check_group_controller!
+      controller_path = @group.metadata_path.join(FeaturePack::CONTROLLER_FILE_NAME)
+      expected_class = "FeaturePack::#{@group_class_name}Controller"
+
+      unless File.exist?(controller_path)
+        raise Thor::Error,
+              "Group controller not found at #{controller_path}. The feature controller must inherit #{expected_class}."
+      end
+
+      controller_class = expected_class.safe_constantize || load_group_controller(controller_path, expected_class)
+
+      return if controller_class.is_a?(Class)
+
+      raise Thor::Error, "#{controller_path} does not define #{expected_class}, which the feature controller inherits."
+    end
+
+    def load_group_controller(controller_path, expected_class)
+      load controller_path
+      expected_class.safe_constantize
+    rescue StandardError, ScriptError => e
+      raise Thor::Error, "Could not load group controller #{controller_path}: #{e.class}: #{e.message}"
+    end
+
     def check_feature_existence!
       if FeaturePack.feature(@group_name.to_sym, @feature_name.to_sym).present?
         raise Thor::Error, "Feature '#{@feature_name}' already exists in group '#{@group_name}'"

data/lib/generators/feature_pack/add_feature/templates/controller.rb.tt

@@ -1,5 +1,7 @@
 # Feature controller for <%= @feature_class_name %>
-class FeaturePack::<%= @group_class_name %>::<%= @feature_class_name %>Controller < FeaturePack::Controller
+class FeaturePack::<%= @group_class_name %>::<%= @feature_class_name %>Controller < FeaturePack::<%= @group_class_name %>Controller
+  # Inherits the group controller and its callbacks. The request receives
+  # @group and @feature automatically based on the route.
   # The 'index' action is already defined in the parent controller
   # Add your feature-specific actions and logic here
   

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: feature_pack
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Gedean Dias
 bindir: bin
 cert_chain: []
-date: 2025-10-06 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -29,6 +29,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Organizes and sets up the architecture of micro-applications within a Rails application,
   enabling segregation, management, and isolation of functionalities, thereby supporting
@@ -40,16 +54,14 @@ extra_rdoc_files: []
 files:
 - README.md
 - doc/feature_pack.md
-- doc/hooks.md
 - lib/feature_pack.rb
-- lib/feature_pack/api/controller.rb
 - lib/feature_pack/controller.rb
 - lib/feature_pack/error.rb
+- lib/feature_pack/feature_controller_setup.rb
 - lib/feature_pack/feature_pack_routes.rb
 - lib/feature_pack/group_controller.rb
 - lib/generators/feature_pack/add_feature/USAGE
 - lib/generators/feature_pack/add_feature/add_feature_generator.rb
-- lib/generators/feature_pack/add_feature/templates/after_initialize.rb.tt
 - lib/generators/feature_pack/add_feature/templates/controller.rb.tt
 - lib/generators/feature_pack/add_feature/templates/doc/readme.md.tt
 - lib/generators/feature_pack/add_feature/templates/manifest.yaml.tt
@@ -59,7 +71,6 @@ files:
 - lib/generators/feature_pack/add_feature/templates/views/partials/_header.html.slim.tt
 - lib/generators/feature_pack/add_group/USAGE
 - lib/generators/feature_pack/add_group/add_group_generator.rb
-- lib/generators/feature_pack/add_group/templates/_group_space/after_initialize.rb.tt
 - lib/generators/feature_pack/add_group/templates/_group_space/controller.rb.tt
 - lib/generators/feature_pack/add_group/templates/_group_space/manifest.yaml.tt
 - lib/generators/feature_pack/add_group/templates/_group_space/routes.rb.tt
@@ -88,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A different approach to organizing Rails app features.
 test_files: []

data/doc/hooks.md

@@ -1,108 +0,0 @@
-# Sistema de Hooks do FeaturePack
-
-## Hook after_initialize
-
-O FeaturePack agora suporta hooks `after_initialize` que permitem executar código customizado após o carregamento de grupos e features.
-
-### Como funciona
-
-Durante o processo de setup do FeaturePack, após todos os grupos e features serem descobertos e configurados, o sistema procura e executa arquivos `after_initialize.rb` específicos.
-
-### Localização dos arquivos
-
-- **Para grupos**: `app/feature_packs/[nome_do_grupo]/_group_space/after_initialize.rb`
-- **Para features**: `app/feature_packs/[nome_do_grupo]/[nome_da_feature]/after_initialize.rb`
-
-### Contexto de execução
-
-Os arquivos `after_initialize.rb` são executados no contexto do objeto group ou feature, permitindo acesso direto a todas as suas propriedades através de `self`.
-
-### Exemplos de uso
-
-#### Hook para grupo
-
-```ruby
-# app/feature_packs/group_admin/_group_space/after_initialize.rb
-
-# Registrar o grupo em um sistema de auditoria
-Rails.logger.info "Grupo #{name} carregado com #{features.size} features"
-
-# Configurar permissões globais do grupo
-features.each do |feature|
-  Rails.logger.info "  - Feature #{feature.name} disponível em #{feature.manifest[:url]}"
-end
-
-# Carregar configurações específicas do grupo
-config_file = File.join(absolute_path, GROUP_SPACE_DIRECTORY, 'config.yml')
-if File.exist?(config_file)
-  @config = YAML.load_file(config_file)
-end
-```
-
-#### Hook para feature
-
-```ruby
-# app/feature_packs/group_admin/feature_users/after_initialize.rb
-
-# Registrar rotas dinâmicas
-Rails.logger.info "Feature #{name} inicializada no grupo #{group.name}"
-
-# Verificar dependências
-required_gems = %w[devise cancancan]
-required_gems.each do |gem_name|
-  unless Gem.loaded_specs.key?(gem_name)
-    Rails.logger.warn "Feature #{name} requer a gem #{gem_name}"
-  end
-end
-
-# Registrar a feature em um sistema de métricas
-StatsD.increment("features.#{group.name}.#{name}.loaded")
-
-# Configurar cache específico da feature
-Rails.cache.write("feature:#{group.name}:#{name}:loaded_at", Time.current)
-```
-
-### Propriedades disponíveis
-
-#### No contexto de grupo
-
-- `name` - Nome do grupo (symbol)
-- `absolute_path` - Caminho absoluto do grupo
-- `relative_path` - Caminho relativo do grupo
-- `features` - Array com todas as features do grupo
-- `manifest` - Hash com dados do manifest.yaml
-- `routes_file` - Caminho do arquivo de rotas
-
-#### No contexto de feature
-
-- `name` - Nome da feature (symbol)
-- `group` - Referência ao grupo pai
-- `absolute_path` - Caminho absoluto da feature
-- `relative_path` - Caminho relativo da feature
-- `namespace` - Módulo Ruby da feature
-- `manifest` - Hash com dados do manifest.yaml
-- `routes_file` - Caminho do arquivo de rotas
-
-### Casos de uso comuns
-
-1. **Logging e auditoria** - Registrar quando grupos/features são carregados
-2. **Validação de dependências** - Verificar se gems ou recursos necessários estão disponíveis
-3. **Configuração dinâmica** - Carregar configurações específicas
-4. **Registro em sistemas externos** - Integrar com sistemas de métricas ou monitoramento
-5. **Inicialização de recursos** - Preparar caches, conexões ou outros recursos
-6. **Verificação de segurança** - Validar permissões ou políticas de acesso
-
-### Boas práticas
-
-1. Mantenha os hooks leves e rápidos - eles são executados durante o boot da aplicação
-2. Use logging apropriado para facilitar debug
-3. Trate exceções adequadamente para não quebrar o processo de inicialização
-4. Evite operações síncronas pesadas (I/O, rede, etc)
-5. Use o hook apenas para configurações que realmente precisam acontecer após a carga completa
-
-### Ordem de execução
-
-1. Todos os grupos são descobertos e configurados
-2. Todas as features são descobertas e configuradas
-3. Hooks `after_initialize` dos grupos são executados
-4. Hooks `after_initialize` das features são executados (na ordem de descoberta)

data/lib/feature_pack/api/controller.rb

@@ -1,3 +0,0 @@
-class FeaturePack::API::Controller < ActionController::API
-
-end

data/lib/generators/feature_pack/add_feature/templates/after_initialize.rb.tt

@@ -1,11 +0,0 @@
-# Hook executado após a inicialização da feature <%= @feature_class_name %>
-# Este arquivo é executado no contexto do objeto feature
-# Você tem acesso a todas as propriedades da feature através de 'self'
-#
-# Exemplo de uso:
-# puts "Feature #{name} foi inicializada!"
-# puts "Grupo da feature: #{group.name}"
-# puts "Caminho absoluto: #{absolute_path}"
-# puts "Namespace: #{namespace}"
-#
-# Adicione seu código customizado abaixo:

data/lib/generators/feature_pack/add_group/templates/_group_space/after_initialize.rb.tt

@@ -1,10 +0,0 @@
-# Hook executado após a inicialização do grupo <%= @class_name %>
-# Este arquivo é executado no contexto do objeto group
-# Você tem acesso a todas as propriedades do grupo através de 'self'
-#
-# Exemplo de uso:
-# puts "Grupo #{name} foi inicializado!"
-# puts "Caminho do grupo: #{absolute_path}"
-# puts "Features do grupo: #{features.map(&:name).join(', ')}"
-#
-# Adicione seu código customizado abaixo: