summoner-engine 0.1.0

data/app/views/summoner/features/index.html.erb

@@ -0,0 +1,55 @@
+<div class="d-flex justify-content-between align-items-center mb-4">
+  <h2 class="mb-0" style="font-size: 1.5rem;">All Features</h2>
+</div>
+
+<div class="card">
+  <table>
+    <thead>
+      <tr>
+        <th>Namespace</th>
+        <th>Key</th>
+        <th>Description</th>
+        <th>Type</th>
+        <th>Default</th>
+        <th>Status</th>
+        <th>Actions</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @features.each do |feature| %>
+        <tr>
+          <td><strong><%= feature.namespace %></strong></td>
+          <td><%= feature.name %></td>
+          <td title="<%= feature.description %>"><%= feature.description.present? ? truncate(feature.description, length: 55) : "-" %></td>
+          <td>
+            <div class="d-flex align-items-center flex-wrap gap-2">
+              <code><%= feature.value_type %></code>
+              <% if feature.match_attribute.present? %>
+                <span title="Matches by: <%= feature.match_attribute %>" style="font-size: 0.7rem; color: var(--text-muted); background: var(--bg-main); padding: 0.15rem 0.4rem; border-radius: 4px; border: 1px solid var(--border-color); white-space: nowrap;">
+                  <span style="opacity: 0.6;">match:</span> <%= feature.match_attribute %>
+                </span>
+              <% end %>
+            </div>
+          </td>
+          <td><code><%= feature.default_value.to_json %></code></td>
+          <td>
+            <span class="badge <%= feature.active ? 'active' : 'inactive' %>">
+              <%= feature.active ? 'Active' : 'Inactive (Removed)' %>
+            </span>
+          </td>
+          <td>
+            <%= link_to "Details", feature_path(feature), class: "btn btn-outline btn-sm", style: "font-size: 0.75rem; text-decoration: none;" %>
+          </td>
+        </tr>
+      <% end %>
+
+      <% if @features.empty? %>
+        <tr>
+          <td colspan="7" class="text-center text-muted" style="padding: 3rem;">
+            No features found. Make sure you have run the YAML sync.
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/summoner/features/show.html.erb

@@ -0,0 +1,120 @@
+<div class="mb-4">
+  <%= link_to "← Back to features", features_path, class: "btn btn-outline btn-sm", style: "text-decoration: none;" %>
+</div>
+
+<div class="card">
+  <div class="card-header d-flex justify-content-between align-items-center">
+    <h2 class="mb-0"><%= @feature.namespace %> / <%= @feature.name %></h2>
+    <div class="d-flex align-items-center gap-2">
+      <% if @feature.last_yaml_value.present? && @feature.default_value != @feature.last_yaml_value %>
+        <span class="text-muted" style="font-size: 0.75rem; margin-right: 0.5rem;">
+          (Diverges from YAML: <code><%= @feature.last_yaml_value %></code>)
+        </span>
+      <% end %>
+      <%= link_to "Edit Default", edit_feature_path(@feature), class: "btn btn-outline btn-sm" %>
+    </div>
+  </div>
+  
+  <div class="card-body">
+    <div class="grid-details">
+      <span>Key:</span> <code><%= @feature.key %></code>
+      <span>Description:</span> <span><%= @feature.description.presence || "No description set" %></span>
+      <span>Type:</span> <code><%= @feature.value_type %></code>
+      
+      <% if @feature.match_attribute.present? %>
+        <span>Matches Attribute:</span> <code><%= @feature.match_attribute %></code>
+      <% end %>
+      
+      <span>Default Value:</span> <code><%= @feature.default_value.to_json %></code>
+      <span>Status:</span> 
+      <div>
+        <span class="badge <%= @feature.active ? 'active' : 'inactive' %>">
+          <%= @feature.active ? 'Active' : 'Removed from YAML' %>
+        </span>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="card">
+  <div class="card-header">
+    <h3 class="mb-0">Overrides (Specific Rules)</h3>
+  </div>
+  
+  <table>
+    <thead>
+      <tr>
+        <th>Entity</th>
+        <th>ID</th>
+        <th>Overridden Value</th>
+        <th>Actions</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @overrides.each do |override| %>
+        <tr>
+          <td><%= override.flaggable_type %></td>
+          <td><%= override.flaggable_id %></td>
+          <td><code><%= override.value.to_json %></code></td>
+          <td>
+            <div class="d-flex gap-2 align-items-center">
+              <%= button_to "Edit", edit_feature_override_path(@feature, override), 
+                  method: :get,
+                  form: { class: "mb-0" },
+                  class: "btn btn-primary btn-sm" %>
+              
+              <%= button_to "Remove", feature_override_path(@feature, override), 
+                  method: :delete, 
+                  data: { confirm: "Are you sure?" },
+                  form: { class: "mb-0" },
+                  class: "btn btn-danger btn-sm" %>
+            </div>
+          </td>
+        </tr>
+      <% end %>
+
+      <% if @overrides.empty? %>
+        <tr>
+          <td colspan="4" class="text-center text-muted" style="padding: 3rem;">
+            No overrides found for this feature.
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<div class="card">
+  <div class="card-header">
+    <h3 class="mb-0">Add New Override</h3>
+  </div>
+  <div class="card-body">
+    <%= form_with model: Summoner::FeatureOverride.new, url: feature_overrides_path(@feature), local: true do |f| %>
+      <div class="d-flex gap-3 align-items-end flex-wrap">
+        
+        <div class="form-group mb-0" style="width: 140px;">
+          <%= f.label :flaggable_type, "Model", class: "form-label" %>
+          <%= f.text_field :flaggable_type, value: @feature.namespace.classify, readonly: true, class: "form-control" %>
+        </div>
+
+        <div class="form-group mb-0" style="width: 100px;">
+          <%= f.label :flaggable_id, "ID", class: "form-label" %>
+          <%= f.number_field :flaggable_id, placeholder: "1", required: true, class: "form-control" %>
+        </div>
+        
+        <div class="form-group mb-0" style="width: 200px;">
+          <%= f.label :value, "Value (#{@feature.value_type})", class: "form-label" %>
+          <% if @feature.value_type == 'boolean' %>
+            <%= f.select :value, [['True', 'true'], ['False', 'false']], {}, class: "form-control" %>
+          <% else %>
+            <%= f.text_field :value, placeholder: @feature.default_value, required: true, class: "form-control" %>
+          <% end %>
+        </div>
+        
+        <div class="form-group mb-0">
+          <%= f.submit "Save Override", class: "btn btn-primary" %>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/summoner/overrides/edit.html.erb

@@ -0,0 +1,37 @@
+<div class="mb-4">
+  <%= link_to "← Back to Feature", feature_path(@feature), class: "btn btn-outline btn-sm", style: "text-decoration: none;" %>
+</div>
+
+<div class="card" style="max-width: 600px;">
+  <div class="card-header">
+    <h2 class="mb-0">Edit Override</h2>
+  </div>
+  
+  <div class="card-body">
+    <div class="grid-details mb-4">
+      <span>Feature:</span> <code><%= @feature.key %></code>
+      <span>Entity:</span> <span><%= @override.flaggable_type %> (ID: <%= @override.flaggable_id %>)</span>
+      <span>Expected Type:</span> <code><%= @feature.value_type %></code>
+      
+      <% if @feature.match_attribute.present? %>
+        <span>Matches Attribute:</span> <code style="background: #fef08a; color: #854d0e;"><%= @feature.match_attribute %></code>
+      <% end %>
+    </div>
+
+    <hr style="border: 0; border-top: 1px solid var(--border-color); margin: 1.5rem 0;">
+
+    <%= form_with model: @override, url: feature_override_path(@feature, @override), method: :patch, local: true do |f| %>
+      <div class="form-group mb-4">
+        <%= f.label :value, "New Value", class: "form-label" %>
+        
+        <% if @feature.value_type == 'boolean' %>
+          <%= f.select :value, [['True', 'true'], ['False', 'false']], { selected: @override.value.to_s }, class: "form-control" %>
+        <% else %>
+          <%= f.text_field :value, value: @override.value.is_a?(String) ? @override.value : @override.value.to_json, class: "form-control" %>
+        <% end %>
+      </div>
+      
+      <%= f.submit "Update Value", class: "btn btn-primary" %>
+    <% end %>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,7 @@
+Summoner::Engine.routes.draw do
+  root to: 'features#index'
+
+  resources :features, only: %i[index show edit update] do
+    resources :overrides, only: %i[create edit update destroy]
+  end
+end

data/lib/generators/summoner/install/install_generator.rb

@@ -0,0 +1,53 @@
+require 'rails/generators/base'
+require 'rails/generators/active_record' 
+
+module Summoner
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs Summoner: creates initializer, features.yml template and migration for features and overrides tables.'
+
+      def create_initializer
+        say 'Creating initializer...', :green
+        copy_file 'summoner.rb', 'config/initializers/summoner.rb'
+      end
+
+      def create_features_yml
+        say 'Creating features.yml template...', :green
+        copy_file 'features.yml', 'config/features.yml'
+      end
+
+      def copy_migrations
+        say 'Creating migration...', :green
+        migration_template 'create_summoner_tables.rb.erb', 'db/migrate/create_summoner_tables.rb'
+      end
+
+      def show_readme
+        readme_text = <<~README
+
+          ==============================================================================
+          Welcome to...
+
+          ██████ ▄▄ ▄▄ ▄▄▄▄▄   ▄█████ ▄▄ ▄▄ ▄▄   ▄▄ ▄▄   ▄▄  ▄▄▄  ▄▄  ▄▄ ▄▄ ▄▄  ▄▄  ▄▄▄▄ 
+            ██   ██▄██ ██▄▄    ▀▀▀▄▄▄ ██ ██ ██▀▄▀██ ██▀▄▀██ ██▀██ ███▄██ ██ ███▄██ ██ ▄▄ 
+            ██   ██ ██ ██▄▄▄   █████▀ ▀███▀ ██   ██ ██   ██ ▀███▀ ██ ▀██ ██ ██ ▀██ ▀███▀ 
+
+          Next steps:
+          1. Run `rails db:migrate` to create the tables.
+          2. Edit your new `config/features.yml` file as desired.
+          3. Run `rails summoner:sync` to save the features to the database!
+          ==============================================================================
+        README
+
+        puts readme_text
+      end
+
+      def self.next_migration_number(dirname)
+        Time.now.utc.strftime('%Y%m%d%H%M%S')
+      end
+    end
+  end
+end

data/lib/generators/summoner/install/templates/create_summoner_tables.rb.erb

@@ -0,0 +1,28 @@
+class CreateSummonerTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :summoner_features do |t|
+      t.string :key, null: false
+      t.string :namespace, null: false
+      t.string :name, null: false
+      t.string :value_type, null: false
+      t.json   :default_value
+      t.json   :last_yaml_value
+      t.text   :description
+      t.text   :last_yaml_description
+      t.string :match_attribute
+      t.boolean :active, default: true
+      t.timestamps
+    end
+    add_index :summoner_features, :key, unique: true
+
+    create_table :summoner_feature_overrides do |t|
+      t.string :feature_key, null: false
+      t.references :flaggable, polymorphic: true, index: { name: 'idx_summoner_overrides_entity' }
+      t.json :value
+      t.timestamps
+    end
+    add_index :summoner_feature_overrides, [:feature_key, :flaggable_id, :flaggable_type], 
+              unique: true, 
+              name: 'idx_summoner_unique_override'
+  end
+end

data/lib/generators/summoner/install/templates/features.yml

@@ -0,0 +1,26 @@
+# =========================================================
+# Summoner - Features Configuration
+# 
+# After any changes to this file, run in the terminal:
+# rails summoner:sync
+# =========================================================
+
+user:
+  # 1. Sample Boolean Feature
+  # Will be injected as `user.new_dashboard?`
+  new_dashboard:
+    default: false
+    description: Enable the new dashboard layout for users.
+
+  # 2. ABAC (Attribute-Based Access Control)
+  # The engine will match this array with the `role` attribute of the user.
+  # Tip: Use ["*"] to enable the feature globally for all users!
+  "can_access_admin?":
+    default: ["admin", "manager"]
+    match_attribute: "role"
+    description: Allow admins and managers to access the admin area.
+
+  # 3. Features of Value (Integer, Float, Json, String)
+  max_items_per_page:
+    default: 20
+    description: Maximum number of items shown per page.

data/lib/generators/summoner/install/templates/summoner.rb

@@ -0,0 +1,10 @@
+Summoner.configure do |config|
+  # Enable or disable the use of Rails.cache for features (Default: true)
+  # config.cache_enabled = true
+
+  # Expiration time for the cache (Default: 1.hour)
+  # config.cache_expires_in = 1.hour
+
+  # Namespace for cache keys (Default: 'summoner')
+  # config.cache_namespace = 'summoner'
+end

data/lib/summoner/configuration.rb

@@ -0,0 +1,20 @@
+module Summoner
+  class Configuration
+    attr_accessor :cache_enabled, :cache_namespace, :cache_expires_in
+
+    def initialize
+      @cache_enabled = true
+      @cache_namespace = 'summoner'
+      @cache_expires_in = 1.hour
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+    configuration
+  end
+end

data/lib/summoner/engine.rb

@@ -0,0 +1,9 @@
+module Summoner
+  class Engine < ::Rails::Engine
+    isolate_namespace Summoner
+
+    initializer "summoner.assets.precompile" do |app|
+      app.config.assets.precompile += %w( summoner/favicon.ico )
+    end
+  end
+end

data/lib/summoner/entity.rb

@@ -0,0 +1,49 @@
+require 'active_support/concern'
+
+module Summoner
+  module Entity
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :summoner_namespace
+
+      self.summoner_namespace = self.name.underscore
+
+      def self.inject_summoner_methods!
+        return unless ActiveRecord::Base.connection.table_exists?(Summoner::Feature.table_name)
+
+        features = Summoner::Feature.where(namespace: summoner_namespace)
+
+        features.each do |feat|
+          method_name = feat.value_type == 'boolean' ? "#{feat.name.chomp('?')}?" : feat.name
+
+          if method_defined?(method_name)
+            Rails.logger.warn "[Summoner] Method #{method_name} already defined in #{self.name}. Skipping feature #{feat.key}."
+            next
+          end
+
+          define_method(method_name) do
+            feature(feat.name)
+          end
+        end
+
+      rescue ActiveRecord::NoDatabaseError, ActiveRecord::StatementInvalid => e
+        Rails.logger.warn "[Summoner] Could not inject feature methods for #{self.name}: #{e.message}. This may be due to the database not being set up yet. Skipping injection."  
+      end
+
+      inject_summoner_methods!
+    end
+
+    class_methods do
+      def feature_namespace(name)
+        self.summoner_namespace = name.to_s
+        inject_summoner_methods!
+      end
+    end
+
+    def feature(name)
+      full_key = "#{self.class.summoner_namespace}.#{name}"
+      Summoner::Fetcher.value_for(full_key, entity: self)
+    end
+  end
+end

data/lib/summoner/fetcher.rb

@@ -0,0 +1,66 @@
+module Summoner
+  class Fetcher
+    def self.value_for(feature_key, entity: nil)
+      config = Summoner.configuration
+
+      return fetch_from_db(feature_key, entity) unless config.cache_enabled
+
+      cache_key = if entity
+        "#{config.cache_namespace}:#{feature_key}:#{entity.class.name.underscore}:#{entity.id}"
+      else
+        "#{config.cache_namespace}:#{feature_key}"
+      end
+
+      Rails.cache.fetch(cache_key, expires_in: config.cache_expires_in) do
+        fetch_from_db(feature_key, entity)
+      end
+    end
+
+    def self.fetch_from_db(feature_key, entity)
+      feature = Summoner::Feature.find_by(key: feature_key)
+      return nil unless feature
+
+      raw_value = resolve_raw_value(feature, entity)      
+
+      if feature.match_attribute.present? && entity.present?
+        return evaluate_match(raw_value, feature.match_attribute, entity)
+      end
+
+      raw_value
+    end
+
+    def self.resolve_raw_value(feature, entity)
+      if entity.present?
+        override = Summoner::FeatureOverride.find_by(
+          feature_key: feature.key,
+          flaggable: entity
+        )
+
+        return override.value if override.present?
+      end
+
+      feature.default_value
+    end
+
+    def self.evaluate_match(allowed_values, attribute, entity)
+      if allowed_values.is_a?(Array) && allowed_values.include?('*')
+        return true
+      elsif allowed_values == '*'
+        return true
+      end
+
+      unless entity.respond_to?(attribute)
+        Rails.logger.warn "[Summoner] Entity #{entity.class.name} does not respond to #{attribute}. Cannot evaluate match for feature #{feature.key}."
+        return false
+      end
+
+      entity_value = entity.public_send(attribute)
+
+      if allowed_values.is_a?(Array)
+        allowed_values.include?(entity_value)
+      else
+        allowed_values == entity_value
+      end
+    end
+  end
+end

data/lib/summoner/sync.rb

@@ -0,0 +1,102 @@
+require 'yaml'
+
+module Summoner
+  class Sync
+    def self.call(yaml_path: nil)
+      yaml_path ||= Rails.root.join('config', 'features.yml')
+
+      unless File.exist?(yaml_path)
+        Rails.logger.warn "[Summoner] No features.yml file found at #{yaml_path}. Skipping synchronization."
+        return false
+      end
+
+      parsed_yaml = YAML.load_file(yaml_path) || {}
+
+      Summoner::Feature.transaction do
+        sync_feature(parsed_yaml)
+        deactivate_missing_features(parsed_yaml)
+      end
+
+      true
+    end
+
+    private
+
+    def self.sync_feature(parsed_yaml)
+      parsed_yaml.each do |namespace, features|
+        next unless features.is_a?(Hash)
+
+        features.each do |raw_name, config|
+          yaml_value = config['default']
+          yaml_description = config['description']
+          inferred_type = infer_type(yaml_value)
+          name = normalize_name(raw_name, inferred_type)
+          key = "#{namespace}.#{name}"
+          feature = Summoner::Feature.find_or_initialize_by(key: key)
+
+          feature.assign_attributes(
+            namespace: namespace,
+            name: name,
+            value_type: inferred_type,
+            match_attribute: config['match_attribute'],
+            active: true
+          )
+
+          if should_update_value?(feature, yaml_value)
+            feature.default_value = yaml_value
+            feature.last_yaml_value = yaml_value
+          end
+
+          if should_update_yaml_field?(feature, yaml_description, :last_yaml_description)
+            feature.description = yaml_description
+            feature.last_yaml_description = yaml_description
+          end
+
+          feature.save!
+        end
+      end
+    end
+
+    def self.should_update_value?(feature, yaml_value)
+      feature.new_record? || feature.last_yaml_value != yaml_value
+    end
+
+    def self.should_update_yaml_field?(feature, yaml_value, tracked_attribute)
+      feature.new_record? || feature.public_send(tracked_attribute) != yaml_value
+    end
+
+    def self.deactivate_missing_features(parsed_yaml)
+      active_keys = []
+
+      parsed_yaml.each do |namespace, features|
+        next unless features.is_a?(Hash)
+
+        features.each do |raw_name, config|
+          yaml_value = config['default']
+          inferred_type = infer_type(yaml_value)
+          name = normalize_name(raw_name, inferred_type)
+
+          active_keys << "#{namespace}.#{name}"
+        end
+      end
+
+      Summoner::Feature.where.not(key: active_keys).update_all(active: false)
+    end
+
+    def self.infer_type(value)
+      case value
+      when TrueClass, FalseClass then 'boolean'
+      when Integer then'integer'
+      when Float then 'float'
+      when Array, Hash then 'json'
+      else 'string' 
+      end
+    end
+
+    def self.normalize_name(name, type)
+      name_str = name.to_s
+
+      type == 'boolean' ? "#{name_str.chomp('?')}?" : name_str
+    end
+  end
+end

data/lib/summoner/version.rb

@@ -0,0 +1,3 @@
+module Summoner
+  VERSION = "0.1.0"
+end

data/lib/summoner.rb

@@ -0,0 +1,11 @@
+Dir[File.join(__dir__, "summoner", "*.rb")].sort.each { |file| require file }
+
+module Summoner
+  def self.get(feature_key)
+    Summoner::Fetcher.value_for(feature_key)
+  end
+
+  def self.active?(feature_key)
+    !!get(feature_key)
+  end
+end

data/lib/tasks/summoner_tasks.rake

@@ -0,0 +1,20 @@
+namespace :summoner do
+  desc 'Sync the .yml file with the engine database'
+  task sync: :environment do
+    puts '[Summoner] Starting synchronization...'
+
+    sleep(2)
+
+    begin
+      result = Summoner::Sync.call
+
+      if result
+        puts '[Summoner] Features synchronized successfully.'
+      else
+        puts '[Summoner] Synchronization skipped due to missing .yml file.'
+      end
+    rescue => e
+      puts "[Summoner] An error occurred while synchronizing features: #{e.message}"
+    end
+  end
+end