propel_facets 0.1.1

data/lib/generators/propel_facets/install_generator.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+require_relative 'unpack_generator'
+##
+# Generator to install propel_facets functionality in a Rails application
+#
+# This creates a COMPLETELY STANDALONE facets system with no gem dependencies.
+# Usage:
+#   rails generate propel_facets:install    # Full standalone system (runtime + generators)  
+#
+# This generator:
+# 1. Installs all runtime code (concerns, utilities, errors, config, etc.)
+# 2. Automatically extracts generator logic to lib/generators/propel_facets/
+# 3. Creates a system that requires NO gem dependencies
+#
+# After installation, you can remove 'propel_facets' from your Gemfile completely.
+# All code is in your application and fully customizable.
+#
+module PropelFacets
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Install PropelFacets functionality for Rails applications"
+
+    def copy_configuration_initializer
+      copy_file "config/propel_facets.rb", "config/initializers/propel_facets.rb"
+    end
+
+    def copy_model_concerns
+      copy_file "models/concerns/model_facet.rb", "app/models/concerns/model_facet.rb"
+    end
+
+    def copy_controller_concerns
+      copy_file "controllers/concerns/facet_renderer.rb", "app/controllers/concerns/facet_renderer.rb"
+      copy_file "controllers/concerns/strong_params_helper.rb", "app/controllers/concerns/strong_params_helper.rb"
+    end
+
+    def copy_utility_classes
+      copy_file "lib/api_params.rb", "lib/api_params.rb"
+    end
+
+    def copy_error_classes
+      copy_file "errors/application_error.rb", "app/errors/application_error.rb"
+      copy_file "errors/missing_facet.rb", "app/errors/missing_facet.rb"
+    end
+
+    def copy_documentation
+      copy_file "doc/json_facet.md", "doc/json_facet.md"
+    end
+
+    def create_application_record_if_needed
+      application_record_path = "app/models/application_record.rb"
+      
+      unless File.exist?(File.join(destination_root, application_record_path))
+        copy_file "models/application_record.rb", application_record_path
+      else
+        say_status :exists, application_record_path, :blue
+        add_propel_facets_to_application_record
+      end
+    end
+
+    def extract_generator_for_customization
+      generator_path = "lib/generators/propel_facets"
+      
+      if File.exist?(generator_path)
+        say ""
+        say "📦 Generator logic already extracted at #{generator_path}/", :blue
+        say "💡 Skipping extraction to preserve your customizations", :cyan
+      else
+        say ""
+        say "📦 Extracting generator logic for full customization...", :blue
+        
+        # Automatically run the unpack generator to extract generator logic
+        invoke PropelFacets::UnpackGenerator, [], { force: false }
+        
+        say ""
+        say "✅ Generator logic extracted to lib/generators/propel_facets/", :green
+        say "💡 Your application is now completely standalone - no gem dependency needed for generators!", :cyan
+        say "🗑️  You can now remove 'propel_facets' from your Gemfile", :yellow
+      end
+    end
+
+    private
+
+    def add_propel_facets_to_application_record
+      inject_into_file "app/models/application_record.rb", after: "class ApplicationRecord < ActiveRecord::Base\n" do
+        <<-RUBY
+  include ModelFacet
+
+  # Default JSON facets for all models
+  json_facet :reference, fields: [:id, :type]
+  json_facet :included, base: :reference
+  json_facet :short, base: :included, include_as: :reference
+  json_facet :details, base: :short, include_as: :included
+
+        RUBY
+      end
+    end
+
+    def show_usage_instructions
+      say ""
+      say "PropelFacets has been installed!", :green
+      
+      say "\n📦 System Status: Completely standalone - no gem dependency!", :green
+      say "\nNext steps:", :yellow
+      say "• Optional: Remove 'propel_facets' from Gemfile (system is fully extracted)", :cyan
+      
+      say ""
+      say "🔧 Configuration:", :bold
+      say "  Edit config/initializers/propel_facets.rb to customize:"
+      say "  • JSON root structure (:data, :model, :class, :none)"
+      say "  • API format (:rest, :jsonapi, :openapi, :graphql, etc.)"
+      say "  • Default facets and inheritance patterns"
+      say "  • Performance and caching options"
+      say ""
+      say "Usage in Models:", :bold
+      say "  class User < ApplicationRecord"
+      say "    json_facet :short, fields: [:name, :email]"
+      say "    json_facet :details, base: :short, fields: [:created_at], methods: [:full_name]"
+      say "  end"
+      say ""
+      say "Usage in Controllers:", :bold
+      say "  class UsersController < ApplicationController"
+      say "    include FacetRenderer"
+      say "    include StrongParamsHelper"
+      say ""
+      say "    connect_facet :short, actions: [:index]"
+      say "    connect_facet :details, actions: [:show]"
+      say ""
+      say "    permitted_params :name, :email, :role"
+      say ""
+      say "    def index"
+      say "      users = User.all"
+      say "      render json: { data: users.map { |u| resource_json(u) } }"
+      say "    end"
+      say "  end"
+      say ""
+      say "Advanced Features:", :bold
+      say "  permitted_unknown_params :metadata, :settings  # Handle dynamic JSON"
+      say "  PropelFacets.configure { |c| c.root = :none }   # Flat JSON structure"
+      
+      say ""
+      say "🎨 Customization:", :bold
+      say "• Generator logic: lib/generators/propel_facets/install_generator.rb", :blue
+      say "• Templates: lib/generators/propel_facets/templates/", :blue
+      say "• Modify any part of the system - it's all yours now!", :cyan
+      
+      say ""
+      say "📖 See doc/json_facet.md for complete documentation.", :blue
+      say "⚙️  See config/initializers/propel_facets.rb for all options.", :blue
+    end
+  end
+end 

data/lib/generators/propel_facets/templates/config/propel_facets.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+# PropelFacets Configuration
+# This file was generated by: rails generate propel_facets:install
+# 
+# PropelFacets provides a flexible system for defining different JSON 
+# representations of models and connecting them to controller actions.
+
+require "rails"
+
+module PropelFacets
+  # This module serves as the namespace for the Propel Facets gem.
+  # PropelFacets provides a flexible system for defining different JSON 
+  # representations of models and connecting them to controller actions.
+  
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+
+  class Configuration
+    # Currently supported options
+    attr_accessor :default_facets,
+                  :strict_mode,
+                  :default_base_facet,
+                  :root,
+                  :api_format
+                  
+    # Future features - not yet implemented
+    # attr_accessor :auto_include_concerns,
+    #               :cache_facets,
+    #               :naming_convention,
+    #               :include_metadata,
+    #               :date_format,
+    #               :null_handling,
+    #               :nested_depth_limit,
+    #               :default_excluded_fields,
+    #               :include_type_information,
+    #               :pagination_format,
+    #               :error_format,
+    #               :performance_logging
+
+    def initialize
+      # Default facets to create on ApplicationRecord
+      @default_facets = %w[reference included short details]
+      
+      # Strict mode - raise errors for missing facets instead of warnings
+      @strict_mode = false
+      
+      # Default base facet for inheritance
+      @default_base_facet = :reference
+      
+      # JSON root structure options: :model, :class, :data, :none
+      # :model - { "user": {...} }, :class - { "User": {...} }
+      # :data - { "data": {...} }, :none - {...} (flat structure)
+      @root = :data
+      
+      # API format standard: :openapi, :rest, :jsonapi, :graphql, :hal, :collection_json, :siren
+      @api_format = :rest
+      
+      # Future configuration options (commented out until implemented):
+      
+      # # Field naming convention: :snake_case, :camelCase, :PascalCase, :kebab_case
+      # @naming_convention = :snake_case
+      # 
+      # # Include metadata (pagination, counts, etc.) in responses
+      # @include_metadata = true
+      # 
+      # # Date/time format: :iso8601, :unix, :rfc3339, or custom strftime format
+      # @date_format = :iso8601
+      # 
+      # # Null value handling: :include, :exclude, :empty_string
+      # @null_handling = :include
+      # 
+      # # Maximum nesting depth to prevent infinite recursion
+      # @nested_depth_limit = 5
+      # 
+      # # Fields to exclude by default from all facets (security sensitive)
+      # @default_excluded_fields = %w[password_digest encrypted_password reset_password_token confirmation_token]
+      # 
+      # # Include model type information in JSON output
+      # @include_type_information = false
+      # 
+      # # Pagination format: :cursor, :offset, :page, :limit_offset
+      # @pagination_format = :page
+      # 
+      # # Error response format: :rails, :jsonapi, :rfc7807, :simple
+      # @error_format = :rails
+      # 
+      # # Enable performance logging for facet rendering
+      # @performance_logging = Rails.env.development?
+    end
+  end
+end
+
+# Configure PropelFacets with recommended defaults
+PropelFacets.configure do |config|
+  # ==========================================
+  # CURRENTLY SUPPORTED CONFIGURATION OPTIONS
+  # ==========================================
+  
+  # JSON root structure: :model, :class, :data, :none
+  # Examples:
+  #   :data  => { "data": { "id": 1, "name": "John" } }
+  #   :model => { "user": { "id": 1, "name": "John" } }
+  #   :none  => { "id": 1, "name": "John" }
+  config.root = :data
+  
+  # API format standard affects response structure and conventions
+  # :rest       - Standard REST API responses
+  # :jsonapi    - JSON:API specification (jsonapi.org)
+  # :openapi    - OpenAPI/Swagger compatible
+  # :graphql    - GraphQL-like nested structure
+  # :hal        - Hypertext Application Language
+  # :collection_json - Collection+JSON hypermedia type
+  # :siren      - Siren hypermedia specification
+  config.api_format = :rest
+  
+  # Default facets available on all models
+  config.default_facets = %w[reference included short details]
+  
+  # Error handling: raise errors (true) or show warnings (false) for missing facets
+  config.strict_mode = false
+  
+  # Default base facet for inheritance chains
+  config.default_base_facet = :reference
+  
+  # ==========================================
+  # FUTURE FEATURES - ROADMAP
+  # ==========================================
+  # Uncomment and configure as features are implemented
+  
+  # # Automatically include ModelFacet in ApplicationRecord (currently manual via generator)
+  # config.auto_include_concerns = true
+  # 
+  # # Cache compiled facets for performance (requires implementation)
+  # config.cache_facets = Rails.env.production?
+  # 
+  # # Field naming convention for JSON output
+  # # :snake_case  - user_name, created_at
+  # # :camelCase   - userName, createdAt  
+  # # :PascalCase  - UserName, CreatedAt
+  # # :kebab_case  - user-name, created-at
+  # config.naming_convention = :snake_case
+  # 
+  # # Include metadata in responses (pagination info, counts, etc.)
+  # config.include_metadata = true
+  # 
+  # # Date/time serialization format
+  # # :iso8601 - "2023-12-01T10:30:00Z"
+  # # :unix    - 1701425400
+  # # :rfc3339 - "2023-12-01T10:30:00.000Z"
+  # # Custom:  - "%Y-%m-%d %H:%M:%S"
+  # config.date_format = :iso8601
+  # 
+  # # How to handle null/nil values in JSON
+  # # :include      - Include null fields: { "name": null }
+  # # :exclude      - Remove null fields: { }
+  # # :empty_string - Convert to empty: { "name": "" }
+  # config.null_handling = :include
+  # 
+  # # Security: Fields to exclude from all facets by default
+  # config.default_excluded_fields = %w[
+  #   password_digest encrypted_password password_hash
+  #   reset_password_token confirmation_token unlock_token
+  #   otp_secret_key encrypted_otp_secret
+  # ]
+  # 
+  # # Performance and safety limits
+  # config.nested_depth_limit = 5
+  # config.performance_logging = Rails.env.development?
+  # 
+  # # API response formats
+  # config.pagination_format = :page   # :cursor, :offset, :page, :limit_offset
+  # config.error_format = :rails       # :rails, :jsonapi, :rfc7807, :simple
+  # config.include_type_information = false  # Include model class name in JSON
+end 

data/lib/generators/propel_facets/templates/controllers/concerns/facet_renderer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+##
+# Provide means to connect a controller to a JSON facetable model.
+#
+# Usage:
+#
+#   class MyController < ApiController
+#     connect_facet :short, actions: [:index]
+#     connect_facet :full, actions: [:show, :update, :create]
+#   end
+#
+module FacetRenderer
+  extend ActiveSupport::Concern
+
+  class_methods do
+    attr_accessor :connected_facets
+
+    def inherited(subclass)
+      super(subclass)
+      subclass.connected_facets = @connected_facets.dup
+    end
+
+    # Directive to connect a facet
+    def connect_facet(facet, actions: nil)
+      @connected_facets = {} if @connected_facets.nil?
+      actual_actions = if actions.nil?
+                         [:index, :create, :show, :update]
+                       else
+                         [actions].flatten
+                       end
+      actual_actions.each do |this_action|
+        @connected_facets[this_action] = facet
+      end
+    end
+
+    # Gets facet for action name or nil
+    def action_facet(action)
+      @connected_facets = {} if @connected_facets.nil?
+      @connected_facets[action]
+    end
+  end
+
+  # To be used by controller to return params with visible and included fields
+  def resource_json(resource)
+    facet = self.class.action_facet(action_name.to_sym)
+    result = resource.as_json(
+      facet: [facet, :index, :default],
+      missing: :noaction
+    )
+
+    # get attachment url in single resource
+    if !resource.respond_to?('length') && resource.class.respond_to?('attachment_reflections')
+      set_attachments(result, resource)
+    else
+      result
+    end
+  end
+
+  # set attachments to result json
+  def set_attachments(result, resource)
+    attachment_fields = {}
+    resource.class.attachment_reflections.keys.each do |name|
+      begin
+        attachment = resource.send(name.to_sym)
+        if attachment.is_a? ActiveStorage::Attached::Many
+          # Note: This is configured to return a maximum of 10 files.
+          # To retrieve all files within a specific parent model, utilize the 'Attachment' class.
+          attachment_fields[name.to_sym] = attachment.take(10).map {|a| url_for(a) if attachment.attached?}.compact
+        else
+          attachment_fields[name.to_sym] = url_for(attachment) if attachment.attached?
+        end
+      rescue StandardError => e
+        Rails.logger.error "Failed to generate URL for attachment #{name}: #{e.message}"
+        next
+      end
+    end
+
+    result&.merge(attachment_fields)
+  end
+end 

data/lib/generators/propel_facets/templates/controllers/concerns/strong_params_helper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+# Helper for defining strong parameters in this application
+#
+# By including this into your controller, you will be allowed to define
+# allowed parameters by calling `permitted_params` and passing a list
+# of field names. This works specially for our application controllers
+# structure where fields are found within `data` JSON property at the
+# very root of a submitted payload
+#
+module StrongParamsHelper
+  extend ActiveSupport::Concern
+
+  class_methods do
+    attr_accessor :all_permitted_params, :all_permitted_unknown_params
+
+    # Directive to define permitted params list
+    def permitted_params(*names)
+      names.each do |name|
+        if @all_permitted_params.nil?
+          @all_permitted_params = [name]
+        elsif @all_permitted_params.include? name
+          warn "[ALREADY PERMITTED] `#{name}` was already permitted"
+        else
+          @all_permitted_params.push name
+        end
+      end
+    end
+
+    def permitted_unknown_params(*names)
+      names.each do |name|
+        if @all_permitted_unknown_params.nil?
+          @all_permitted_unknown_params = [name]
+        elsif @all_permitted_unknown_params.include? name
+          warn "[ALREADY PERMITTED] `#{name}` was already permitted"
+        else
+          @all_permitted_unknown_params.push name
+        end
+      end
+    end
+  end
+
+  # To be used by controller to parse params as strong params
+  def resource_params
+    permitted = self.class.all_permitted_params
+
+    api_params = ApiParams.new(params, request)
+    permitted_params = api_params.permit(permitted)
+
+    if self.class.all_permitted_unknown_params.present?
+      self.class.all_permitted_unknown_params.each do |key|
+        next unless (params.include?(:data) && !params[:data][key].nil?) || !params[key].nil?
+        permitted_params = permitted_params.merge({ key => api_params.force_permit(key) })
+      end
+    end
+
+    permitted_params
+  end
+end 

data/lib/generators/propel_facets/templates/doc/json_facet.md

@@ -0,0 +1,78 @@
+# JSON Facet System
+
+JSON Facets provide a flexible way to define different JSON representations of your ActiveRecord models and automatically connect them to controller actions.
+
+## Model Usage
+
+Define facets in your models by including the `ModelFacet` concern:
+
+```ruby
+class User < ApplicationRecord
+  # Basic facet with specific fields
+  json_facet :short, fields: [:name, :email, :created_at]
+  
+  # Extended facet building on another
+  json_facet :details, base: :short, 
+             fields: [:updated_at], 
+             methods: [:full_name], 
+             include: [:posts]
+             
+  # With associations
+  json_facet :with_posts, base: :short, include: [:posts]
+end
+```
+
+## Controller Usage
+
+Connect facets to controller actions:
+
+```ruby
+class UsersController < ApplicationController
+  include FacetRenderer
+  include StrongParamsHelper
+  
+  connect_facet :short, actions: [:index]
+  connect_facet :details, actions: [:show, :update]
+  
+  permitted_params :name, :email, :role
+  
+  def index
+    users = User.all
+    render json: { data: users.map { |user| resource_json(user) } }
+  end
+  
+  def show
+    user = User.find(params[:id])
+    render json: { data: resource_json(user) }
+  end
+end
+```
+
+## Parameter Handling
+
+For complex JSON parameters:
+
+```ruby
+class ProductsController < ApplicationController
+  include StrongParamsHelper
+  
+  permitted_params :name, :price, :category
+  permitted_unknown_params :metadata, :settings  # For dynamic JSON structures
+end
+```
+
+## Facet Options
+
+- `fields`: Array of model attributes to include
+- `methods`: Array of model methods to call and include
+- `include`: Array of associations to include
+- `include_as`: How to render included associations (uses their facets)
+- `base`: Extend another facet definition
+
+## Default Facets
+
+All models inherit these default facets from `ApplicationRecord`:
+- `:reference` - Basic id and type
+- `:included` - Extends reference
+- `:short` - General purpose summary view  
+- `:details` - Comprehensive view with associations 

data/lib/generators/propel_facets/templates/errors/application_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+##
+# Base class for all errors raised by this application
+#
+class ApplicationError < StandardError
+  def initialize(msg = 'Application error')
+    super
+  end
+end 

data/lib/generators/propel_facets/templates/errors/missing_facet.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+##
+# Error thrown when a facet cannot be found
+#
+# This is only thrown when you pass `{ missing: :error }` as part of
+# `as_json` options.
+#
+class MissingFacet < ApplicationError
+  def initialize(msg = 'Facet not found to render JSON')
+    super
+  end
+end 

data/lib/generators/propel_facets/templates/lib/api_params.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+##
+# Helps manipulating client parameters for our API
+#
+class ApiParams
+  def initialize(params, request = nil)
+    @params = if params.is_a? ActionController::Parameters
+                params
+              else
+                ActionController::Parameters.new(params)
+              end
+    @user_agent = request&.user_agent
+  end
+
+  def permit(params)
+    if !@params.include?(:data) && command_line_agent
+      @params.permit params
+    else
+      @params.require(:data).permit(params)
+    end
+  end
+
+  def force_permit(key)
+    if !@params.include?(:data) && command_line_agent
+      @params[key].permit!
+    else
+      if @params[:data][key].is_a?(Array) # for nested attributes
+        @params[:data][key].each do |field|
+          field.permit!
+        end
+      else
+        @params[:data][key].permit!
+      end
+    end
+  end
+
+  CMDLINE_AGENTS = %w[httpie curl].freeze
+
+  def command_line_agent
+    agent = @user_agent&.downcase
+    CMDLINE_AGENTS.any? ->(prefix) { agent&.start_with? prefix }
+  end
+end 

data/lib/generators/propel_facets/templates/models/application_record.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class ApplicationRecord < ActiveRecord::Base
+  include ModelFacet
+
+  primary_abstract_class
+
+  # Default JSON facets for all models
+  json_facet :reference, fields: [:id, :type]
+  json_facet :included, base: :reference
+  json_facet :short, base: :included, include_as: :reference
+  json_facet :details, base: :short, include_as: :included
+end