facera 0.1.0

data/lib/facera/openapi_generator.rb

@@ -0,0 +1,338 @@
+module Facera
+  class OpenAPIGenerator
+    attr_reader :facet_name, :facet, :core
+
+    def initialize(facet_name)
+      @facet_name = facet_name
+      @facet = Registry.facets[facet_name]
+      raise "Facet #{facet_name} not found" unless @facet
+      @core = Registry.cores[@facet.core_name]
+      raise "Core #{@facet.core_name} not found" unless @core
+    end
+
+    def generate
+      {
+        openapi: '3.0.3',
+        info: info_section,
+        servers: servers_section,
+        paths: paths_section,
+        components: components_section
+      }
+    end
+
+    private
+
+    def info_section
+      {
+        title: "#{@facet_name.to_s.capitalize} API",
+        description: @facet.description || "#{@facet_name} facet of #{@core.name} core",
+        version: Facera::VERSION,
+        contact: {
+          name: 'Facera Framework'
+        }
+      }
+    end
+
+    def servers_section
+      config = Facera.configuration
+      base_path = config.base_path
+      facet_path = config.path_for_facet(@facet_name)
+
+      [{
+        url: "#{base_path}#{facet_path}",
+        description: "#{@facet_name.to_s.capitalize} API"
+      }]
+    end
+
+    def paths_section
+      paths = {}
+
+      # Health endpoint
+      paths['/health'] = {
+        get: {
+          summary: 'Health check',
+          tags: ['Health'],
+          responses: {
+            '200' => {
+              description: 'Service is healthy',
+              content: {
+                'application/json' => {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      status: { type: 'string', example: 'ok' },
+                      facet: { type: 'string', example: @facet_name.to_s },
+                      core: { type: 'string', example: @core.name.to_s },
+                      timestamp: { type: 'string', format: 'date-time' }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+
+      # Entity endpoints
+      @facet.field_visibilities.each do |entity_name, visibility|
+        entity = @core.entities[entity_name]
+
+        # Collection endpoints
+        collection_path = "/#{entity_name}s"
+        paths[collection_path] = {}
+
+        # POST (create)
+        if capability_allowed?("create_#{entity_name}")
+          paths[collection_path][:post] = create_operation(entity_name, entity, visibility)
+        end
+
+        # GET (list)
+        if capability_allowed?("list_#{entity_name}s")
+          paths[collection_path][:get] = list_operation(entity_name, entity, visibility)
+        end
+
+        # Single resource endpoints
+        resource_path = "/#{entity_name}s/{id}"
+        paths[resource_path] = {}
+
+        # GET (retrieve)
+        if capability_allowed?("get_#{entity_name}")
+          paths[resource_path][:get] = get_operation(entity_name, entity, visibility)
+        end
+
+        # Action endpoints
+        @core.capabilities.each do |cap_name, capability|
+          next unless capability.type == :action
+          next unless capability.entity == entity_name
+          next unless capability_allowed?(cap_name)
+
+          action_name = cap_name.to_s.sub("#{entity_name}_", '')
+          action_path = "/#{entity_name}s/{id}/#{action_name}"
+
+          paths[action_path] = {
+            post: action_operation(cap_name, capability, entity, visibility)
+          }
+        end
+      end
+
+      paths
+    end
+
+    def create_operation(entity_name, entity, visibility)
+      {
+        summary: "Create a new #{entity_name}",
+        tags: [entity_name.to_s.capitalize],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json' => {
+              schema: request_schema(entity_name, entity, visibility)
+            }
+          }
+        },
+        responses: {
+          '201' => {
+            description: "#{entity_name.to_s.capitalize} created successfully",
+            content: {
+              'application/json' => {
+                schema: response_schema(entity_name, entity, visibility)
+              }
+            }
+          },
+          '400' => error_response('Validation error'),
+          '401' => error_response('Unauthorized')
+        }
+      }
+    end
+
+    def list_operation(entity_name, entity, visibility)
+      {
+        summary: "List #{entity_name}s",
+        tags: [entity_name.to_s.capitalize],
+        parameters: [
+          { name: 'limit', in: 'query', schema: { type: 'integer', default: 20 }, description: 'Number of results' },
+          { name: 'offset', in: 'query', schema: { type: 'integer', default: 0 }, description: 'Pagination offset' }
+        ],
+        responses: {
+          '200' => {
+            description: "List of #{entity_name}s",
+            content: {
+              'application/json' => {
+                schema: {
+                  type: 'array',
+                  items: response_schema(entity_name, entity, visibility)
+                }
+              }
+            }
+          },
+          '401' => error_response('Unauthorized')
+        }
+      }
+    end
+
+    def get_operation(entity_name, entity, visibility)
+      {
+        summary: "Get a #{entity_name}",
+        tags: [entity_name.to_s.capitalize],
+        parameters: [
+          { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }
+        ],
+        responses: {
+          '200' => {
+            description: "#{entity_name.to_s.capitalize} details",
+            content: {
+              'application/json' => {
+                schema: response_schema(entity_name, entity, visibility)
+              }
+            }
+          },
+          '404' => error_response('Not found'),
+          '401' => error_response('Unauthorized')
+        }
+      }
+    end
+
+    def action_operation(cap_name, capability, entity, visibility)
+      action_name = cap_name.to_s.sub("#{capability.entity}_", '')
+
+      {
+        summary: "#{action_name.capitalize} a #{capability.entity}",
+        tags: [capability.entity.to_s.capitalize],
+        parameters: [
+          { name: 'id', in: 'path', required: true, schema: { type: 'string', format: 'uuid' } }
+        ],
+        requestBody: capability.required_params.any? || capability.optional_params.any? ? {
+          content: {
+            'application/json' => {
+              schema: {
+                type: 'object',
+                properties: (capability.required_params + capability.optional_params)
+                  .reject { |p| p == :id }
+                  .map { |param| [param, { type: 'string' }] }
+                  .to_h,
+                required: capability.required_params.reject { |p| p == :id }
+              }
+            }
+          }
+        } : nil,
+        responses: {
+          '200' => {
+            description: "#{capability.entity.to_s.capitalize} #{action_name}d successfully",
+            content: {
+              'application/json' => {
+                schema: response_schema(capability.entity, entity, visibility)
+              }
+            }
+          },
+          '400' => error_response('Validation error'),
+          '404' => error_response('Not found'),
+          '401' => error_response('Unauthorized')
+        }
+      }.compact
+    end
+
+    def request_schema(entity_name, entity, visibility)
+      properties = {}
+      required = []
+
+      entity.attributes.each do |attr_name, attr|
+        next if attr.immutable? && attr_name != :id
+
+        properties[attr_name] = attribute_to_schema(attr)
+        required << attr_name if attr.required?
+      end
+
+      {
+        type: 'object',
+        properties: properties,
+        required: required
+      }
+    end
+
+    def response_schema(entity_name, entity, visibility)
+      properties = {}
+      visible_fields = visibility.visible_field_names(entity)
+
+      visible_fields.each do |field_name|
+        if entity.attributes[field_name]
+          properties[field_name] = attribute_to_schema(entity.attributes[field_name])
+        end
+      end
+
+      # Add computed fields
+      visibility.computed_fields.each do |computed_name, _block|
+        properties[computed_name] = { type: 'string', description: 'Computed field' }
+      end
+
+      {
+        type: 'object',
+        properties: properties
+      }
+    end
+
+    def attribute_to_schema(attr)
+      schema = { type: type_to_openapi(attr.type) }
+      schema[:enum] = attr.enum_values if attr.enum_values.any?
+      schema[:format] = 'uuid' if attr.type == :uuid
+      schema[:format] = 'date-time' if attr.type == :datetime
+      schema
+    end
+
+    def type_to_openapi(type)
+      case type
+      when :string, :text, :uuid then 'string'
+      when :integer then 'integer'
+      when :decimal, :money then 'number'
+      when :boolean then 'boolean'
+      when :datetime, :date then 'string'
+      when :json, :jsonb then 'object'
+      else 'string'
+      end
+    end
+
+    def error_response(description)
+      {
+        description: description,
+        content: {
+          'application/json' => {
+            schema: {
+              type: 'object',
+              properties: {
+                error: { type: 'string' },
+                message: { type: 'string' }
+              }
+            }
+          }
+        }
+      }
+    end
+
+    def capability_allowed?(cap_name)
+      @facet.capability_allowed?(cap_name.to_sym)
+    end
+
+    def components_section
+      {
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT'
+          }
+        }
+      }
+    end
+
+    class << self
+      def for_facet(facet_name)
+        new(facet_name).generate
+      end
+
+      def generate_all
+        Registry.facets.keys.map do |facet_name|
+          [facet_name, for_facet(facet_name)]
+        end.to_h
+      end
+    end
+  end
+end

data/lib/facera/railtie.rb

@@ -0,0 +1,51 @@
+if defined?(Rails)
+  module Facera
+    class Railtie < Rails::Railtie
+      railtie_name :facera
+
+      config.facera = Facera.configuration
+
+      # Auto-load facet and core definitions
+      initializer "facera.load_definitions", before: :load_config_initializers do
+        # Use Facera's loader for automatic discovery
+        Facera.load_all!
+      end
+
+      # Auto-mount facets after initialization
+      initializer "facera.auto_mount", after: :load_config_initializers do |app|
+        # Check if user has created a facera initializer
+        facera_initializer = Rails.root.join('config/initializers/facera.rb')
+
+        if File.exist?(facera_initializer)
+          # User has control via initializer, don't auto-mount unless they call it
+          Rails.logger.info "Facera: Configuration found at config/initializers/facera.rb"
+        else
+          # No initializer, auto-mount with defaults
+          if Registry.facets.any?
+            Rails.logger.info "Facera: Auto-mounting #{Registry.facets.count} facets..."
+            Facera.auto_mount!(app)
+          end
+        end
+      end
+
+      # Reload facets in development mode
+      config.to_prepare do
+        if Rails.env.development?
+          Facera.load_all!
+        end
+      end
+
+      # Add rake tasks
+      rake_tasks do
+        load 'facera/tasks/routes.rake'
+      end
+
+      # Add generators
+      generators do
+        require 'facera/generators/install_generator'
+        require 'facera/generators/core_generator'
+        require 'facera/generators/facet_generator'
+      end
+    end
+  end
+end

data/lib/facera/registry.rb

@@ -0,0 +1,34 @@
+module Facera
+  module Registry
+    class << self
+      def cores
+        @cores ||= {}
+      end
+
+      def facets
+        @facets ||= {}
+      end
+
+      def register_core(name, core)
+        cores[name.to_sym] = core
+      end
+
+      def register_facet(name, facet)
+        facets[name.to_sym] = facet
+      end
+
+      def find_core(name)
+        cores[name.to_sym] or raise Error, "Core '#{name}' not found"
+      end
+
+      def find_facet(name)
+        facets[name.to_sym] or raise Error, "Facet '#{name}' not found"
+      end
+
+      def reset!
+        @cores = {}
+        @facets = {}
+      end
+    end
+  end
+end

data/lib/facera/tasks/routes.rake

@@ -0,0 +1,66 @@
+namespace :facera do
+  desc "Show all Facera routes"
+  task routes: :environment do
+    puts "\n" + "=" * 80
+    puts "Facera Routes"
+    puts "=" * 80
+
+    if Facera::Registry.facets.empty?
+      puts "\nNo facets defined."
+      puts "Create facets in app/facets/ or use 'rails g facera:facet NAME --core=CORE'"
+      puts "=" * 80 + "\n"
+      next
+    end
+
+    Facera::Registry.facets.each do |name, facet|
+      config = Facera.configuration
+      next unless config.facet_enabled?(name)
+
+      path_prefix = "#{config.base_path}#{config.path_for_facet(name)}"
+      api = Facera::Grape::APIGenerator.for_facet(name)
+
+      puts "\n#{name.to_s.upcase} (#{facet.description})"
+      puts "  Base: #{path_prefix}"
+      puts "  Capabilities: #{facet.allowed_capabilities.count}/#{facet.core.capabilities.count}"
+      puts "  Routes:"
+
+      # Group routes by resource
+      api.routes.group_by { |r| r.path.split('/')[1] }.each do |resource, routes|
+        routes.each do |route|
+          method = route.request_method.ljust(7)
+          path = "#{path_prefix}#{route.path.gsub('(.:format)', '')}"
+          puts "    #{method} #{path}"
+        end
+      end
+    end
+
+    puts "\n" + "=" * 80 + "\n"
+  end
+
+  desc "Show Facera configuration"
+  task config: :environment do
+    config = Facera.configuration
+
+    puts "\n" + "=" * 80
+    puts "Facera Configuration"
+    puts "=" * 80
+    puts "\nGeneral:"
+    puts "  Base path: #{config.base_path}"
+    puts "  Version: #{config.version}"
+    puts "  Dashboard: #{config.dashboard}"
+    puts "  Generate docs: #{config.generate_docs}"
+
+    puts "\nFacets:"
+    puts "  Defined: #{Facera::Registry.facets.count}"
+    puts "  Enabled: #{Facera::Registry.facets.count - config.disabled_facets.count}"
+    puts "  Disabled: #{config.disabled_facets.join(', ')}" if config.disabled_facets.any?
+
+    puts "\nCores:"
+    puts "  Defined: #{Facera::Registry.cores.count}"
+    Facera::Registry.cores.each do |name, core|
+      puts "    #{name}: #{core.entities.count} entities, #{core.capabilities.count} capabilities"
+    end
+
+    puts "\n" + "=" * 80 + "\n"
+  end
+end

data/lib/facera/version.rb

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

data/lib/facera.rb

@@ -0,0 +1,35 @@
+require_relative "facera/version"
+require_relative "facera/registry"
+require_relative "facera/context"
+require_relative "facera/attribute"
+require_relative "facera/entity"
+require_relative "facera/invariant"
+require_relative "facera/capability"
+require_relative "facera/core"
+require_relative "facera/errors"
+require_relative "facera/error_formatter"
+require_relative "facera/field_visibility"
+require_relative "facera/capability_access"
+require_relative "facera/facet"
+require_relative "facera/adapter"
+require_relative "facera/dsl"
+require_relative "facera/executor"
+require_relative "facera/grape"
+require_relative "facera/configuration"
+require_relative "facera/loader"
+require_relative "facera/introspection"
+require_relative "facera/openapi_generator"
+require_relative "facera/introspection_api"
+require_relative "facera/auto_mount"
+
+# Load Rails integration if Rails is present
+require_relative "facera/railtie" if defined?(Rails)
+
+module Facera
+  class Error < StandardError; end
+
+  # Convenience method to create APIs
+  def self.api_for(facet_name)
+    Grape::APIGenerator.for_facet(facet_name)
+  end
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: facera
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Juan Carlos Garcia
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-03-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: grape
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: grape-entity
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+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.
+email:
+- jugade92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- ".github/workflows/gem-push.yml"
+- ".github/workflows/ruby.yml"
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/01_core_dsl.rb
+- examples/02_facet_system.rb
+- examples/03_api_generation.rb
+- examples/04_auto_mounting.rb
+- examples/05_adapters.rb
+- examples/README.md
+- examples/server/README.md
+- examples/server/adapters/payment_adapter.rb
+- examples/server/application.rb
+- examples/server/config.ru
+- examples/server/config/facera.rb
+- examples/server/cores/payment_core.rb
+- examples/server/facets/external_facet.rb
+- examples/server/facets/internal_facet.rb
+- examples/server/facets/operator_facet.rb
+- facera.gemspec
+- img/facera.png
+- lib/facera.rb
+- lib/facera/adapter.rb
+- lib/facera/attribute.rb
+- lib/facera/auto_mount.rb
+- lib/facera/capability.rb
+- lib/facera/capability_access.rb
+- lib/facera/configuration.rb
+- lib/facera/context.rb
+- lib/facera/core.rb
+- lib/facera/dsl.rb
+- lib/facera/entity.rb
+- lib/facera/error_formatter.rb
+- lib/facera/errors.rb
+- lib/facera/executor.rb
+- lib/facera/facet.rb
+- lib/facera/field_visibility.rb
+- lib/facera/generators/core_generator.rb
+- lib/facera/generators/facet_generator.rb
+- lib/facera/generators/install_generator.rb
+- lib/facera/generators/templates/core.rb.tt
+- lib/facera/generators/templates/facet.rb.tt
+- lib/facera/grape.rb
+- lib/facera/grape/api_generator.rb
+- lib/facera/grape/endpoint_generator.rb
+- lib/facera/grape/entity_generator.rb
+- lib/facera/introspection.rb
+- lib/facera/introspection_api.rb
+- lib/facera/invariant.rb
+- lib/facera/loader.rb
+- lib/facera/openapi_generator.rb
+- lib/facera/railtie.rb
+- lib/facera/registry.rb
+- lib/facera/tasks/routes.rake
+- lib/facera/version.rb
+homepage: https://github.com/jcagarcia/facera
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jcagarcia/facera
+  source_code_uri: https://github.com/jcagarcia/facera
+  changelog_uri: https://github.com/jcagarcia/facera/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key: 
+specification_version: 4
+summary: A Ruby framework for building multi-facet APIs from a single semantic core
+test_files: []