facera 0.1.0

data/examples/server/facets/internal_facet.rb

@@ -0,0 +1,33 @@
+# Internal Facet
+# Service-to-service API for internal microservices
+# Full access to all fields and operations
+
+Facera.define_facet(:internal, core: :payment) do
+  description "Internal service-to-service API"
+
+  # Expose all fields for internal services
+  expose :payment do
+    fields :all
+
+    # Add computed fields for internal use
+    computed :age_in_seconds do
+      created_at ? (Time.now - created_at).to_i : 0
+    end
+
+    computed :is_recent do
+      age_in_seconds < 3600  # Less than 1 hour old
+    end
+  end
+
+  # Allow all capabilities
+  allow_capabilities :all
+
+  # No scoping - internal services can see everything
+  # They're trusted and may need to operate on any payment
+
+  # Detailed errors for debugging
+  error_verbosity :detailed
+
+  # Audit all internal operations (in production, this would log to a service)
+  audit_all_operations user: :system
+end

data/examples/server/facets/operator_facet.rb

@@ -0,0 +1,48 @@
+# Operator Facet
+# Admin/support operator API with enhanced visibility
+# Used by support tools and admin dashboards
+
+Facera.define_facet(:operator, core: :payment) do
+  description "Support operator and admin tools API"
+
+  # Expose all fields plus additional operational data
+  expose :payment do
+    fields :all
+
+    # Add operator-specific computed fields
+    computed :customer_name do
+      # In a real app: Customer.find(customer_id).name
+      "Customer #{customer_id[0..7]}"
+    end
+
+    computed :merchant_name do
+      # In a real app: Merchant.find(merchant_id).name
+      "Merchant #{merchant_id[0..7]}"
+    end
+
+    computed :time_in_current_state do
+      if status == :confirmed && confirmed_at
+        Time.now - confirmed_at
+      elsif status == :cancelled && cancelled_at
+        Time.now - cancelled_at
+      elsif created_at
+        Time.now - created_at
+      else
+        0
+      end
+    end
+  end
+
+  # Allow all capabilities (operators can do everything)
+  allow_capabilities :all
+
+  # No scoping - operators need to see all payments for support
+  # But we audit all their actions
+  audit_all_operations user: :current_operator
+
+  # Detailed errors for troubleshooting
+  error_verbosity :detailed
+
+  # Structured format for better tooling integration
+  format :structured
+end

data/facera.gemspec

@@ -0,0 +1,30 @@
+require_relative 'lib/facera/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "facera"
+  spec.version       = Facera::VERSION
+  spec.authors       = ["Juan Carlos Garcia"]
+  spec.email         = ["jugade92@gmail.com"]
+
+  spec.summary       = "A Ruby framework for building multi-facet APIs from a single semantic core"
+  spec.description   = "Facera allows you to define your system once as a semantic core and expose it through multiple facets, each tailored to different consumers while remaining logically consistent."
+  spec.homepage      = "https://github.com/jcagarcia/facera"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "grape", "~> 2.0"
+  spec.add_dependency "grape-entity", "~> 1.0"
+end

data/lib/facera/adapter.rb

@@ -0,0 +1,83 @@
+module Facera
+  # Base module for adapters
+  # Adapters implement the actual business logic for capabilities
+  #
+  # Example:
+  #   class PaymentAdapter
+  #     include Facera::Adapter
+  #
+  #     def create_payment(params)
+  #       Payment.create!(params)
+  #     end
+  #
+  #     def get_payment(id:)
+  #       Payment.find(id)
+  #     end
+  #   end
+  module Adapter
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Returns the core name this adapter is for
+      # Inferred from class name: PaymentAdapter -> :payment
+      def core_name
+        name.gsub(/Adapter$/, '').split('::').last.underscore.to_sym
+      end
+    end
+
+    # Default implementation for capabilities
+    # Subclasses override specific methods
+
+    def create(params)
+      raise NotImplementedError, "#{self.class}#create not implemented"
+    end
+
+    def get(id:)
+      raise NotImplementedError, "#{self.class}#get not implemented"
+    end
+
+    def list(filters = {})
+      raise NotImplementedError, "#{self.class}#list not implemented"
+    end
+
+    def action(capability_name, params)
+      raise NotImplementedError, "#{self.class}#action(#{capability_name}) not implemented"
+    end
+  end
+
+  # Adapter registry
+  class AdapterRegistry
+    @adapters = {}
+
+    class << self
+      def register(core_name, adapter_class)
+        @adapters[core_name.to_sym] = adapter_class
+      end
+
+      def get(core_name)
+        @adapters[core_name.to_sym]
+      end
+
+      def all
+        @adapters
+      end
+
+      def clear!
+        @adapters = {}
+      end
+    end
+  end
+end
+
+# String underscore helper
+class String
+  def underscore
+    gsub(/::/, '/')
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr('-', '_')
+      .downcase
+  end unless method_defined?(:underscore)
+end

data/lib/facera/attribute.rb

@@ -0,0 +1,95 @@
+module Facera
+  class Attribute
+    attr_reader :name, :type, :options
+
+    VALID_TYPES = [
+      :string,
+      :integer,
+      :float,
+      :boolean,
+      :uuid,
+      :money,
+      :timestamp,
+      :datetime,
+      :date,
+      :enum,
+      :hash,
+      :array
+    ].freeze
+
+    def initialize(name, type, **options)
+      @name = name.to_sym
+      @type = type.to_sym
+      @options = options
+
+      validate_type!
+      validate_options!
+    end
+
+    def required?
+      @options[:required] == true
+    end
+
+    def immutable?
+      @options[:immutable] == true
+    end
+
+    def default_value
+      @options[:default]
+    end
+
+    def enum_values
+      @options[:values] || []
+    end
+
+    def validate_value(value)
+      return true if value.nil? && !required?
+      return false if value.nil? && required?
+
+      case type
+      when :string
+        value.is_a?(String)
+      when :integer
+        value.is_a?(Integer)
+      when :float
+        value.is_a?(Float) || value.is_a?(Integer)
+      when :boolean
+        [true, false].include?(value)
+      when :uuid
+        value.is_a?(String) && uuid_format?(value)
+      when :money
+        value.is_a?(Numeric) && value >= 0
+      when :timestamp, :datetime
+        value.is_a?(Time) || value.is_a?(DateTime)
+      when :date
+        value.is_a?(Date)
+      when :enum
+        enum_values.include?(value)
+      when :hash
+        value.is_a?(Hash)
+      when :array
+        value.is_a?(Array)
+      else
+        true
+      end
+    end
+
+    private
+
+    def validate_type!
+      unless VALID_TYPES.include?(type)
+        raise Error, "Invalid attribute type '#{type}'. Valid types: #{VALID_TYPES.join(', ')}"
+      end
+    end
+
+    def validate_options!
+      if type == :enum && enum_values.empty?
+        raise Error, "Enum attribute '#{name}' must specify :values option"
+      end
+    end
+
+    def uuid_format?(value)
+      value.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+    end
+  end
+end

data/lib/facera/auto_mount.rb

@@ -0,0 +1,124 @@
+module Facera
+  class AutoMount
+    attr_reader :app, :config, :mounted_facets
+
+    def initialize(app = nil, config: {})
+      @app = app || detect_app
+      @config = Facera.configuration
+      @mounted_facets = {}
+      @logger = Logger.new($stdout)
+    end
+
+    def mount!
+      log_header
+      discover_definitions
+      mount_facets
+      mount_introspection if @config.introspection
+      mount_dashboard if @config.dashboard
+      log_summary
+      @mounted_facets
+    end
+
+    private
+
+    def log_header
+      @logger.info "\n" + "=" * 80
+      @logger.info "💎 Facera v#{Facera::VERSION} - Auto-Mounting"
+      @logger.info "=" * 80
+    end
+
+    def discover_definitions
+      # Use Facera's loader to auto-discover cores, adapters, and facets
+      loader = Loader.new(logger: @logger)
+      loader.load_all!
+
+      @logger.info "\n📊 Found:"
+      @logger.info "  Cores: #{Registry.cores.count}"
+      @logger.info "  Adapters: #{AdapterRegistry.all.count}"
+      @logger.info "  Facets: #{Registry.facets.count}"
+    end
+
+    def mount_facets
+      @logger.info "\n🚀 Mounting facets:"
+
+      Registry.facets.each do |name, facet|
+        next unless @config.facet_enabled?(name)
+
+        path = "#{@config.base_path}#{@config.path_for_facet(name)}"
+        api = Grape::APIGenerator.for_facet(name)
+
+        mount_api(api, path)
+
+        @mounted_facets[name] = {
+          path: path,
+          api: api,
+          endpoints: api.routes.count
+        }
+
+        @logger.info "  ✓ #{name.to_s.ljust(15)} → #{path.ljust(25)} (#{api.routes.count} endpoints)"
+      end
+    end
+
+    def mount_introspection
+      path = "#{@config.base_path}/facera"
+      api = IntrospectionAPI
+
+      mount_api(api, path)
+
+      @logger.info "\n📚 Introspection API:"
+      @logger.info "  ✓ Mounted at #{path}"
+      @logger.info "  • #{path}/introspect - Full introspection"
+      @logger.info "  • #{path}/cores - All cores"
+      @logger.info "  • #{path}/facets - All facets"
+      @logger.info "  • #{path}/openapi - OpenAPI specs"
+    end
+
+    def mount_api(api, path)
+      if defined?(Rails)
+        Rails.application.routes.draw do
+          mount api => path
+        end
+      elsif @app.respond_to?(:map)
+        # Rack app with map support
+        @app.map(path) { run api }
+      else
+        # Simple rack app
+        @app = Rack::URLMap.new(
+          path => api,
+          '/' => @app
+        )
+      end
+    end
+
+    def mount_dashboard
+      # Dashboard will be implemented in a future phase
+      # For now, just log that it would be mounted
+      @logger.info "\n🎨 Dashboard: #{@config.base_path}/facera/ui (coming soon)"
+    end
+
+    def log_summary
+      @logger.info "\n" + "=" * 80
+      @logger.info "✨ Facera ready! #{@mounted_facets.count} facets mounted"
+      @logger.info "=" * 80 + "\n"
+    end
+
+    def detect_app
+      if defined?(Rails)
+        Rails.application
+      elsif defined?(Sinatra::Application)
+        Sinatra::Application
+      else
+        # Return a basic Rack builder
+        Rack::Builder.new
+      end
+    end
+  end
+
+  class << self
+    def auto_mount!(app = nil, config: {})
+      AutoMount.new(app, config: config).mount!
+    end
+  end
+end
+
+require 'logger'

data/lib/facera/capability.rb

@@ -0,0 +1,117 @@
+module Facera
+  class Capability
+    attr_reader :name, :type, :entity_name, :required_params, :optional_params,
+                :preconditions, :validations, :transitions, :field_setters, :action_name,
+                :execute_block
+
+    VALID_TYPES = [:create, :get, :update, :delete, :list, :action].freeze
+
+    def initialize(name, type:)
+      @name = name.to_sym
+      @type = type.to_sym
+      @entity_name = nil
+      @required_params = []
+      @optional_params = []
+      @preconditions = []
+      @validations = []
+      @transitions = []
+      @field_setters = {}
+      @action_name = nil
+      @execute_block = nil
+
+      validate_type!
+    end
+
+    def entity(name)
+      @entity_name = name.to_sym
+    end
+
+    def requires(*param_names)
+      param_names.each do |param_name|
+        @required_params << param_name.to_sym
+      end
+    end
+
+    def optional(*param_names)
+      param_names.each do |param_name|
+        @optional_params << param_name.to_sym
+      end
+    end
+
+    def precondition(&block)
+      @preconditions << block
+    end
+
+    def validates(&block)
+      @validations << block
+    end
+
+    def transitions_to(state)
+      @transitions << state.to_sym
+    end
+
+    def sets(field_values)
+      @field_setters.merge!(field_values)
+    end
+
+    def action(name)
+      @action_name = name.to_sym
+    end
+
+    def returns(type)
+      @return_type = type.to_sym
+    end
+
+    def execute(&block)
+      @execute_block = block
+    end
+
+    def has_execute_block?
+      !@execute_block.nil?
+    end
+
+    def filterable(*param_names)
+      @filterable_params ||= []
+      param_names.each do |param_name|
+        @filterable_params << param_name.to_sym
+      end
+    end
+
+    def filterable_params
+      @filterable_params || []
+    end
+
+    def validate_params(params)
+      errors = []
+
+      # Check required parameters
+      required_params.each do |param|
+        if params[param].nil? && params[param.to_s].nil?
+          errors << "#{param} is required"
+        end
+      end
+
+      errors
+    end
+
+    def check_preconditions(context)
+      preconditions.all? do |precondition|
+        context.instance_eval(&precondition)
+      end
+    end
+
+    def validate_business_rules(context)
+      validations.all? do |validation|
+        context.instance_eval(&validation)
+      end
+    end
+
+    private
+
+    def validate_type!
+      unless VALID_TYPES.include?(type)
+        raise Error, "Invalid capability type '#{type}'. Valid types: #{VALID_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/facera/capability_access.rb

@@ -0,0 +1,59 @@
+module Facera
+  class CapabilityAccess
+    attr_reader :allowed_capabilities, :denied_capabilities, :scopes
+
+    def initialize
+      @allowed_capabilities = :all
+      @denied_capabilities = []
+      @scopes = {}
+    end
+
+    def allow(*capability_names)
+      if capability_names.first == :all
+        @allowed_capabilities = :all
+      else
+        @allowed_capabilities = [] if @allowed_capabilities == :all
+        @allowed_capabilities.concat(capability_names.map(&:to_sym))
+      end
+    end
+
+    def deny(*capability_names)
+      @denied_capabilities.concat(capability_names.map(&:to_sym))
+    end
+
+    def scope(capability_name, &block)
+      raise Error, "Scope for '#{capability_name}' must have a block" unless block_given?
+      @scopes[capability_name.to_sym] = block
+    end
+
+    def allowed?(capability_name)
+      cap_sym = capability_name.to_sym
+
+      # Check if explicitly denied
+      return false if @denied_capabilities.include?(cap_sym)
+
+      # Check if in allowed list
+      if @allowed_capabilities == :all
+        true
+      else
+        @allowed_capabilities.include?(cap_sym)
+      end
+    end
+
+    def scope_for(capability_name)
+      @scopes[capability_name.to_sym]
+    end
+
+    def has_scope?(capability_name)
+      @scopes.key?(capability_name.to_sym)
+    end
+
+    def allowed_capability_names(core)
+      if @allowed_capabilities == :all
+        core.capabilities.keys - @denied_capabilities
+      else
+        @allowed_capabilities - @denied_capabilities
+      end
+    end
+  end
+end

data/lib/facera/configuration.rb

@@ -0,0 +1,83 @@
+module Facera
+  class Configuration
+    attr_accessor :base_path, :version, :dashboard, :generate_docs, :introspection
+    attr_reader :facet_paths, :disabled_facets, :authentication_handlers, :middleware_handlers
+
+    def initialize
+      @base_path = '/api'
+      @version = 'v1'
+      @dashboard = true
+      @generate_docs = true
+      @introspection = true
+      @facet_paths = {}
+      @disabled_facets = []
+      @authentication_handlers = {}
+      @middleware_handlers = {}
+    end
+
+    def facet_path(facet_name, path)
+      @facet_paths[facet_name.to_sym] = path
+    end
+
+    def disable_facet(facet_name)
+      @disabled_facets << facet_name.to_sym
+    end
+
+    def authenticate(facet_name, &block)
+      raise Error, "Authentication block required for facet '#{facet_name}'" unless block_given?
+      @authentication_handlers[facet_name.to_sym] = block
+    end
+
+    def middleware_for(facet_name, &block)
+      raise Error, "Middleware block required for facet '#{facet_name}'" unless block_given?
+      @middleware_handlers[facet_name.to_sym] = block
+    end
+
+    def path_for_facet(facet_name)
+      @facet_paths[facet_name.to_sym] || default_path_for(facet_name)
+    end
+
+    def facet_enabled?(facet_name)
+      !@disabled_facets.include?(facet_name.to_sym)
+    end
+
+    def authentication_handler_for(facet_name)
+      @authentication_handlers[facet_name.to_sym]
+    end
+
+    def middleware_handler_for(facet_name)
+      @middleware_handlers[facet_name.to_sym]
+    end
+
+    private
+
+    def default_path_for(facet_name)
+      case facet_name.to_sym
+      when :external
+        "/#{@version}"
+      when :internal
+        "/internal/#{@version}"
+      when :operator
+        "/operator/#{@version}"
+      when :agent
+        "/agent/#{@version}"
+      else
+        "/#{facet_name}/#{@version}"
+      end
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/facera/context.rb

@@ -0,0 +1,29 @@
+module Facera
+  # Lightweight context object for block evaluation
+  # Replaces OpenStruct with a simpler, faster implementation
+  class Context
+    def initialize(data = {})
+      @data = data.transform_keys(&:to_sym)
+    end
+
+    def method_missing(method, *args)
+      if args.empty?
+        # Getter
+        @data[method]
+      elsif method.to_s.end_with?('=')
+        # Setter
+        @data[method.to_s.chomp('=').to_sym] = args.first
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @data.key?(method) || method.to_s.end_with?('=') || super
+    end
+
+    def to_h
+      @data
+    end
+  end
+end