facera 0.1.0

data/lib/facera/field_visibility.rb

@@ -0,0 +1,69 @@
+module Facera
+  class FieldVisibility
+    attr_reader :entity_name, :visible_fields, :hidden_fields, :field_aliases, :computed_fields
+
+    def initialize(entity_name)
+      @entity_name = entity_name.to_sym
+      @visible_fields = nil  # nil means all fields visible
+      @hidden_fields = []
+      @field_aliases = {}
+      @computed_fields = {}
+    end
+
+    def fields(*field_names)
+      if field_names.first == :all
+        @visible_fields = :all
+      else
+        @visible_fields = field_names.map(&:to_sym)
+      end
+    end
+
+    def hide(*field_names)
+      @hidden_fields = field_names.map(&:to_sym)
+    end
+
+    def alias_field(source, as:)
+      @field_aliases[source.to_sym] = as.to_sym
+    end
+
+    def computed(field_name, &block)
+      raise Error, "Computed field '#{field_name}' must have a block" unless block_given?
+      @computed_fields[field_name.to_sym] = block
+    end
+
+    def visible?(field_name)
+      field_sym = field_name.to_sym
+
+      # If explicitly hidden, not visible
+      return false if @hidden_fields.include?(field_sym)
+
+      # If visible_fields is nil or :all, visible (unless hidden)
+      return true if @visible_fields.nil? || @visible_fields == :all
+
+      # Otherwise check if in visible list
+      @visible_fields.include?(field_sym)
+    end
+
+    def aliased_name(field_name)
+      @field_aliases[field_name.to_sym] || field_name
+    end
+
+    def visible_field_names(entity)
+      base_fields = if @visible_fields == :all || @visible_fields.nil?
+                      entity.attributes.keys
+                    else
+                      @visible_fields
+                    end
+
+      # Filter out hidden fields
+      base_fields.reject { |f| @hidden_fields.include?(f) }
+    end
+
+    def all_visible_fields(entity)
+      base_fields = visible_field_names(entity)
+      computed_field_names = @computed_fields.keys
+
+      base_fields + computed_field_names
+    end
+  end
+end

data/lib/facera/generators/core_generator.rb

@@ -0,0 +1,23 @@
+if defined?(Rails)
+  require 'rails/generators/base'
+
+  module Facera
+    module Generators
+      class CoreGenerator < Rails::Generators::NamedBase
+        source_root File.expand_path('../templates', __FILE__)
+
+        desc "Generate a new Facera core"
+
+        def create_core_file
+          template 'core.rb.tt', File.join('app/cores', "#{file_name}_core.rb")
+        end
+
+        private
+
+        def entity_name
+          file_name.singularize
+        end
+      end
+    end
+  end
+end

data/lib/facera/generators/facet_generator.rb

@@ -0,0 +1,25 @@
+if defined?(Rails)
+  require 'rails/generators/base'
+
+  module Facera
+    module Generators
+      class FacetGenerator < Rails::Generators::NamedBase
+        source_root File.expand_path('../templates', __FILE__)
+
+        desc "Generate a new Facera facet"
+
+        class_option :core, type: :string, required: true, desc: "The core this facet belongs to"
+
+        def create_facet_file
+          template 'facet.rb.tt', File.join('app/facets', "#{file_name}_facet.rb")
+        end
+
+        private
+
+        def core_name
+          options[:core]
+        end
+      end
+    end
+  end
+end

data/lib/facera/generators/install_generator.rb

@@ -0,0 +1,64 @@
+if defined?(Rails)
+  require 'rails/generators/base'
+
+  module Facera
+    module Generators
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path('../templates', __FILE__)
+
+        desc "Install Facera in your Rails application"
+
+        def create_directories
+          empty_directory 'app/cores'
+          empty_directory 'app/facets'
+        end
+
+        def create_initializer
+          create_file 'config/initializers/facera.rb', <<~RUBY
+            # Facera configuration
+            Facera.configure do |config|
+              # Base path for all APIs
+              # config.base_path = '/api'
+
+              # API version
+              # config.version = 'v1'
+
+              # Enable dashboard
+              # config.dashboard = true
+
+              # Custom facet paths
+              # config.facet_path :external, '/v1'
+              # config.facet_path :internal, '/internal/v1'
+
+              # Disable specific facets
+              # config.disable_facet :agent
+
+              # Authentication handlers
+              # config.authenticate :external do |request|
+              #   token = request.headers['Authorization']
+              #   User.find_by_token(token)
+              # end
+            end
+
+            # Auto-mount all defined facets
+            # This will discover and mount facets from app/facets/
+            # Facera.auto_mount!
+          RUBY
+        end
+
+        def show_readme
+          say "\n"
+          say "=" * 70
+          say "Facera installed successfully!"
+          say "=" * 70
+          say "\nNext steps:"
+          say "  1. Generate a core:  rails g facera:core payment"
+          say "  2. Generate a facet: rails g facera:facet external --core=payment"
+          say "  3. Start your server and visit /api/v1/health"
+          say "\nDocumentation: https://github.com/jcagarcia/facera"
+          say "=" * 70 + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/facera/generators/templates/core.rb.tt

@@ -0,0 +1,49 @@
+# <%= class_name %> Core
+Facera.define_core(:<%= file_name %>) do
+  # Define your entity
+  entity :<%= entity_name %> do
+    attribute :id, :uuid, immutable: true
+    attribute :created_at, :timestamp, immutable: true
+    attribute :updated_at, :timestamp
+
+    # Add your attributes here
+    # attribute :name, :string, required: true
+    # attribute :status, :enum, values: [:active, :inactive]
+  end
+
+  # Define your invariants (business rules)
+  # invariant :example_rule, description: "Example invariant" do
+  #   # Your validation logic
+  #   true
+  # end
+
+  # Define your capabilities
+  capability :create_<%= entity_name %>, type: :create do
+    entity :<%= entity_name %>
+    requires :id
+    # Add required params
+    # optional :name
+  end
+
+  capability :get_<%= entity_name %>, type: :get do
+    entity :<%= entity_name %>
+    requires :id
+  end
+
+  capability :list_<%= file_name %>, type: :list do
+    entity :<%= entity_name %>
+    optional :limit, :offset
+    # filterable :status
+  end
+
+  capability :update_<%= entity_name %>, type: :update do
+    entity :<%= entity_name %>
+    requires :id
+    # optional :name
+  end
+
+  capability :delete_<%= entity_name %>, type: :delete do
+    entity :<%= entity_name %>
+    requires :id
+  end
+end

data/lib/facera/generators/templates/facet.rb.tt

@@ -0,0 +1,23 @@
+# <%= class_name %> Facet
+Facera.define_facet(:<%= file_name %>, core: :<%= core_name %>) do
+  description "<%= class_name %> API"
+
+  # Control field visibility
+  # expose :<%= core_name.singularize %> do
+  #   fields :id, :name, :created_at
+  #   # hide :sensitive_field
+  #   # alias_field :created_at, as: :createdAt
+  # end
+
+  # Control capability access
+  # allow_capabilities :create_<%= core_name.singularize %>, :get_<%= core_name.singularize %>, :list_<%= core_name %>
+  # deny_capabilities :delete_<%= core_name.singularize %>
+
+  # Add scoping
+  # scope :list_<%= core_name %> do
+  #   { user_id: current_user.id }
+  # end
+
+  # Set error verbosity
+  error_verbosity :minimal
+end

data/lib/facera/grape/api_generator.rb

@@ -0,0 +1,59 @@
+require 'grape'
+
+module Facera
+  module Grape
+    class APIGenerator
+      def self.for_facet(facet_name)
+        facet = Registry.find_facet(facet_name)
+        core = facet.core
+
+        api_class = Class.new(::Grape::API) do
+          version 'v1', using: :header, vendor: 'facera'
+          format :json
+          content_type :json, 'application/json'
+
+          # Store facet reference
+          define_singleton_method(:facet) { facet }
+
+          # Add helpers
+          helpers do
+            def current_user
+              # Placeholder - in real implementation this would authenticate
+              @current_user ||= { id: 'user-123' }
+            end
+
+            def current_facet
+              self.class.facet
+            end
+          end
+
+          # Generate endpoints for each allowed capability
+          facet.allowed_capabilities.each do |capability_name|
+            capability = core.find_capability(capability_name)
+            next unless capability.entity_name
+
+            entity_name = capability.entity_name
+            resource_name = entity_name.to_s.pluralize
+
+            # Create resource block
+            resource resource_name do
+              EndpointGenerator.generate_for(self, capability, facet)
+            end
+          end
+
+          # Add a health check endpoint
+          get :health do
+            {
+              status: 'ok',
+              facet: facet.name,
+              core: core.name,
+              timestamp: Time.now.iso8601
+            }
+          end
+        end
+
+        api_class
+      end
+    end
+  end
+end

data/lib/facera/grape/endpoint_generator.rb

@@ -0,0 +1,316 @@
+module Facera
+  module Grape
+    class EndpointGenerator
+      def self.generate_for(api_class, capability, facet)
+        case capability.type
+        when :create
+          generate_create(api_class, capability, facet)
+        when :get
+          generate_get(api_class, capability, facet)
+        when :update
+          generate_update(api_class, capability, facet)
+        when :delete
+          generate_delete(api_class, capability, facet)
+        when :list
+          generate_list(api_class, capability, facet)
+        when :action
+          generate_action(api_class, capability, facet)
+        end
+      end
+
+      private
+
+      def self.generate_create(api_class, capability, facet)
+        entity_name = capability.entity_name
+        resource_name = entity_name.to_s.pluralize
+        entity = facet.core.find_entity(entity_name)
+        entity_class = EntityGenerator.for(entity, facet)
+
+        # Pre-calculate param types
+        param_types = {}
+        capability.required_params.each do |param|
+          param_types[param] = param_type_for(param, entity)
+        end
+        capability.optional_params.each do |param|
+          param_types[param] = param_type_for(param, entity)
+        end
+
+        api_class.class_eval do
+          desc "Create a #{entity_name}" do
+            success entity_class
+            failure [[400, 'Validation Error'], [401, 'Unauthorized']]
+          end
+
+          params do
+            capability.required_params.each do |param|
+              requires param, type: param_types[param]
+            end
+
+            capability.optional_params.each do |param|
+              optional param, type: param_types[param]
+            end
+          end
+
+          post do
+            result = Executor.run(
+              facet: facet,
+              capability: capability,
+              params: declared(params),
+              context: { current_user: current_user }
+            )
+
+            present result, with: entity_class
+          rescue Facera::ValidationError => e
+            error!({ error: 'validation', errors: e.errors }, 400)
+          rescue Facera::UnauthorizedError => e
+            error!({ error: 'unauthorized', message: e.message }, 401)
+          end
+        end
+      end
+
+      def self.generate_get(api_class, capability, facet)
+        entity_name = capability.entity_name
+        resource_name = entity_name.to_s.pluralize
+        entity = facet.core.find_entity(entity_name)
+        entity_class = EntityGenerator.for(entity, facet)
+
+        api_class.class_eval do
+          desc "Get a #{entity_name}" do
+            success entity_class
+            failure [[404, 'Not Found'], [401, 'Unauthorized']]
+          end
+
+          params do
+            requires :id, type: String, desc: "#{entity_name.to_s.capitalize} ID"
+          end
+
+          get ':id' do
+            result = Executor.run(
+              facet: facet,
+              capability: capability,
+              params: { id: params[:id] },
+              context: { current_user: current_user }
+            )
+
+            present result, with: entity_class
+          rescue Facera::NotFoundError => e
+            error!({ error: 'not_found', message: e.message }, 404)
+          rescue Facera::UnauthorizedError => e
+            error!({ error: 'unauthorized', message: e.message }, 401)
+          end
+        end
+      end
+
+      def self.generate_list(api_class, capability, facet)
+        entity_name = capability.entity_name
+        resource_name = entity_name.to_s.pluralize
+        entity = facet.core.find_entity(entity_name)
+        collection_class = EntityGenerator.for_collection(entity, facet)
+
+        api_class.class_eval do
+          desc "List #{resource_name}" do
+            success collection_class
+            failure [[401, 'Unauthorized']]
+          end
+
+          params do
+            optional :limit, type: Integer, default: 20, desc: 'Number of items to return'
+            optional :offset, type: Integer, default: 0, desc: 'Number of items to skip'
+
+            capability.filterable_params.each do |param|
+              optional param, type: String, desc: "Filter by #{param}"
+            end
+
+            capability.optional_params.each do |param|
+              next if [:limit, :offset].include?(param)
+              optional param, type: String
+            end
+          end
+
+          get do
+            result = Executor.run(
+              facet: facet,
+              capability: capability,
+              params: declared(params),
+              context: { current_user: current_user }
+            )
+
+            present result, with: collection_class
+          rescue Facera::UnauthorizedError => e
+            error!({ error: 'unauthorized', message: e.message }, 401)
+          end
+        end
+      end
+
+      def self.generate_update(api_class, capability, facet)
+        entity_name = capability.entity_name
+        entity = facet.core.find_entity(entity_name)
+        entity_class = EntityGenerator.for(entity, facet)
+
+        # Pre-calculate param types
+        param_types = {}
+        capability.optional_params.each do |param|
+          param_types[param] = param_type_for(param, entity)
+        end
+
+        api_class.class_eval do
+          desc "Update a #{entity_name}" do
+            success entity_class
+            failure [[400, 'Validation Error'], [404, 'Not Found'], [401, 'Unauthorized']]
+          end
+
+          params do
+            requires :id, type: String
+
+            capability.optional_params.each do |param|
+              optional param, type: param_types[param]
+            end
+          end
+
+          patch ':id' do
+            result = Executor.run(
+              facet: facet,
+              capability: capability,
+              params: declared(params),
+              context: { current_user: current_user }
+            )
+
+            present result, with: entity_class
+          rescue Facera::ValidationError => e
+            error!({ error: 'validation', errors: e.errors }, 400)
+          rescue Facera::NotFoundError => e
+            error!({ error: 'not_found', message: e.message }, 404)
+          rescue Facera::UnauthorizedError => e
+            error!({ error: 'unauthorized', message: e.message }, 401)
+          end
+        end
+      end
+
+      def self.generate_delete(api_class, capability, facet)
+        entity_name = capability.entity_name
+
+        api_class.class_eval do
+          desc "Delete a #{entity_name}" do
+            success { { success: Boolean, id: String } }
+            failure [[404, 'Not Found'], [401, 'Unauthorized']]
+          end
+
+          params do
+            requires :id, type: String
+          end
+
+          delete ':id' do
+            result = Executor.run(
+              facet: facet,
+              capability: capability,
+              params: { id: params[:id] },
+              context: { current_user: current_user }
+            )
+
+            present result
+          rescue Facera::NotFoundError => e
+            error!({ error: 'not_found', message: e.message }, 404)
+          rescue Facera::UnauthorizedError => e
+            error!({ error: 'unauthorized', message: e.message }, 401)
+          end
+        end
+      end
+
+      def self.generate_action(api_class, capability, facet)
+        entity_name = capability.entity_name
+        action_name = capability.action_name || extract_action_name(capability.name)
+        entity = facet.core.find_entity(entity_name)
+        entity_class = EntityGenerator.for(entity, facet)
+
+        # Pre-calculate param types
+        param_types = {}
+        capability.required_params.each do |param|
+          next if param == :id
+          param_types[param] = param_type_for(param, entity)
+        end
+        capability.optional_params.each do |param|
+          param_types[param] = param_type_for(param, entity)
+        end
+
+        api_class.class_eval do
+          desc "#{action_name.to_s.humanize} a #{entity_name}" do
+            success entity_class
+            failure [[400, 'Validation Error'], [404, 'Not Found'], [401, 'Unauthorized'], [422, 'Precondition Failed']]
+          end
+
+          params do
+            requires :id, type: String
+
+            capability.required_params.each do |param|
+              next if param == :id
+              requires param, type: param_types[param]
+            end
+
+            capability.optional_params.each do |param|
+              optional param, type: param_types[param]
+            end
+          end
+
+          post ":id/#{action_name}" do
+            result = Executor.run(
+              facet: facet,
+              capability: capability,
+              params: declared(params),
+              context: { current_user: current_user }
+            )
+
+            present result, with: entity_class
+          rescue Facera::ValidationError => e
+            error!({ error: 'validation', errors: e.errors }, 400)
+          rescue Facera::PreconditionError => e
+            error!({ error: 'precondition', message: e.message }, 422)
+          rescue Facera::NotFoundError => e
+            error!({ error: 'not_found', message: e.message }, 404)
+          rescue Facera::UnauthorizedError => e
+            error!({ error: 'unauthorized', message: e.message }, 401)
+          end
+        end
+      end
+
+      def self.extract_action_name(capability_name)
+        # Extract action from capability name like "confirm_payment" -> "confirm"
+        name_parts = capability_name.to_s.split('_')
+        name_parts[0...-1].join('_').to_sym
+      end
+
+      def self.param_type_for(param_name, entity)
+        attr = entity.find_attribute(param_name)
+        return String unless attr
+
+        case attr.type
+        when :string, :uuid then String
+        when :integer then Integer
+        when :float, :money then Float
+        when :boolean then Boolean
+        when :hash then Hash
+        when :array then Array
+        else String
+        end
+      end
+    end
+  end
+end
+
+# Add humanize method if not available
+unless String.method_defined?(:humanize)
+  class String
+    def humanize
+      self.gsub('_', ' ').capitalize
+    end
+  end
+end
+
+# Add pluralize method if not available
+unless String.method_defined?(:pluralize)
+  class String
+    def pluralize
+      return self if self.end_with?('s')
+      "#{self}s"
+    end
+  end
+end