facera 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f537d48a2710c89255f9c09da919bc6bba7be4569c3cb92e0b1830a583b708ad
+  data.tar.gz: aabc5be766d5039722c23becb91242da22b0e67f72f4521c9ac1d54d11a67335
+SHA512:
+  metadata.gz: e667c5784b928f1f3747bd368521d85cb2227112d18c9ea8f1b86459fe1d15f0756c01757595a5cb29fae925095ba9441beb4aa461b74b50abf292ace3ea12f1
+  data.tar.gz: e7a1286414b83d21a0ffc2a15781e9c6e4608be4c998dfdcf7a2caea20fcf43a7d9ad90d4f63da61409cf077b163921378f616d80fa4f9396576bc0e6a52d584

data/.github/workflows/gem-push.yml

@@ -0,0 +1,42 @@
+name: Ruby Gem
+
+on: workflow_dispatch
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby 3.2
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.2'
+
+    - name: Get Gem Version
+      id: get-version
+      run: |
+        VERSION=$(ruby -r './lib/facera/version.rb' -e "puts Facera::VERSION")
+        echo "::set-output name=version::$VERSION"
+      shell: bash
+
+    - name: Publish to RubyGems
+      run: |
+        gem fetch facera -v ${{ steps.get-version.outputs.version }}
+        if [ $? -eq 1 ]; then
+          echo "Gem version already exists on RubyGems. Skipping the push to RubyGems."
+          exit 0
+        fi
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push *.gem
+      shell: bash
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.github/workflows/ruby.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        ruby-version: ['3.2', '3.3', '3.4', '4.0']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,39 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# RSpec files
+.rspec_status
+
+# Bundler
+Gemfile.lock
+.bundle/
+vendor/bundle
+
+# Documentation cache and generated files
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+# Environment files
+/.env
+/.env.local
+
+# macOS
+.DS_Store
+
+# IDE files
+/.idea/
+/.vscode/
+*.swp
+*.swo
+*~

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-09
+
+### Added
+
+#### Core Framework
+- **Core DSL** - Define domain models with entities, capabilities, and invariants
+  - Entity definitions with typed attributes (string, integer, uuid, money, enum, etc.)
+  - Four capability types: create, get, list, action
+  - Business invariants with validation blocks
+  - State transitions and preconditions
+  - Field setters and required/optional parameters
+
+- **Facet System** - Consumer-specific API projections
+  - Field visibility control (explicit fields, hide fields, expose all)
+  - Capability access control (allow/deny capabilities)
+  - Computed fields with custom logic
+  - Error verbosity levels (minimal, detailed, structured)
+  - Audit logging configuration
+  - Capability scoping for filtering
+
+- **Adapter Pattern** - Business logic implementation
+  - Adapter base module for implementing capabilities
+  - Auto-discovery from `adapters/` directory
+  - Auto-linking to cores by naming convention
+  - Inline execute blocks for simple logic
+  - Priority system (execute block > adapter > mock)
+  - Full method naming convention support
+
+- **API Generation** - Auto-generated REST APIs using Grape
+  - REST endpoints for all capabilities (POST, GET, LIST)
+  - Action endpoints (POST /{entity}/:id/{action})
+  - Health check endpoints
+  - Automatic parameter validation
+  - Automatic precondition checking
+  - Invariant validation
+  - Field filtering by facet
+
+- **Auto-Mounting** - Convention over configuration
+  - Auto-discovery from `cores/`, `adapters/`, and `facets/` directories
+  - Support for multiple directory structures (app/, lib/, root)
+  - Automatic Grape API generation and mounting
+  - Rack::Builder integration
+  - Rails Railtie integration
+  - Startup logging with emoji indicators 💎🔌🎭🚀📚✨
+
+- **Introspection API** - Runtime API exploration
+  - Full introspection endpoint (`/facera/introspect`)
+  - Core inspection (`/facera/cores`, `/facera/cores/:name`)
+  - Facet inspection (`/facera/facets`, `/facera/facets/:name`)
+  - Mounted configuration endpoint (`/facera/mounted`)
+  - Programmatic introspection via `Facera::Introspection`
+
+- **OpenAPI Generation** - Auto-generated API documentation
+  - OpenAPI 3.0 spec generation for all facets
+  - Complete paths, schemas, parameters, and responses
+  - Per-facet specs (`/facera/openapi/:facet`)
+  - All facets spec (`/facera/openapi`)
+  - Programmatic generation via `Facera::OpenAPIGenerator`
+
+- **Configuration System**
+  - Base path and versioning
+  - Custom facet paths
+  - Conditional facet enabling/disabling
+  - Feature flags (introspection, dashboard, docs)
+  - Authentication hooks per facet
+
+#### Developer Experience
+- **Examples** - Five complete working examples
+  - 01_core_dsl.rb - Core definition basics
+  - 02_facet_system.rb - Multiple facets from one core
+  - 03_api_generation.rb - Auto-generated APIs
+  - 04_auto_mounting.rb - Zero-config mounting
+  - 05_adapters.rb - Business logic implementation
+  - Runnable server in examples/server/
+
+- **Documentation** - Comprehensive wiki
+  - Home - Complete navigation and quick reference
+  - Core Concepts - Understanding the facet model
+  - Defining Cores - Entity and capability guide
+  - Defining Facets - Field visibility and access control
+  - Implementing Business Logic - Adapter pattern guide
+  - API Generation - REST endpoint documentation
+  - Auto-Mounting - Convention-based discovery guide
+  - Configuration - Authentication and feature flags
+  - Introspection - Runtime exploration guide
+  - Examples - Complete working examples
+  - Deployment - Production deployment guides
+  - Architecture - Design principles and internals
+  - Contributing - Contribution guidelines
+
+- **Testing** - Complete test suite
+  - 82 RSpec examples covering all components
+  - Core DSL tests
+  - Facet system tests
+  - Loader and registry tests
+  - Configuration tests
+  - 100% test coverage for critical paths
+
+- **CI/CD** - GitHub Actions workflow
+  - Ruby CI for versions 3.2, 3.3, 3.4, 4.0
+  - Automated test runs on push/PR
+  - Build status badge in README
+
+#### Internal Infrastructure
+- Registry system for cores and facets
+- Loader with auto-discovery
+- Executor with capability execution logic
+- Error formatter with verbosity levels
+- Custom Context class (Ruby 4 compatible, replaces OpenStruct)
+- Grape API generator
+- Grape entity generator with computed fields
+
+### Technical Details
+- **Ruby Version**: Requires Ruby >= 3.2.0
+- **Dependencies**:
+  - grape ~> 2.0
+  - grape-entity ~> 1.0
+- **License**: MIT
+- **Framework Integration**: Rack, Rails, Sinatra
+
+### Breaking Changes
+- This is the initial release, no breaking changes
+
+### Migration Guide
+- N/A (initial release)
+
+### Contributors
+- Juan Carlos Garcia (@jcagarcia)

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in facera.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "rack-test", "~> 2.0"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Carlos García del Canto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,309 @@
+# Facera
+
+**One semantic core. Multiple API facets. Zero duplication.**
+
+Facera is a Ruby framework for building **multi-facet APIs** from a single semantic core. Define your domain model once, then expose different views for different consumers—all guaranteed consistent by design.
+
+<img src="img/facera.png" alt="Facera logo" width="250"/>
+
+[![Gem Version](https://badge.fury.io/rb/facera.svg)](https://badge.fury.io/rb/facera)
+[![Ruby CI](https://github.com/jcagarcia/facera/actions/workflows/ruby.yml/badge.svg)](https://github.com/jcagarcia/facera/actions/workflows/ruby.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## Why Facera?
+
+Modern systems expose APIs to many different consumers, leading to duplicated endpoints, inconsistent representations, and maintenance burden. **Facera solves this** by letting you define your system **once** as a semantic core, then automatically generate multiple consistent API facets.
+
+### Before Facera
+```
+3 separate APIs × 5 endpoints = 15 implementations
++ 3 serializers + 3 auth systems + 3 test suites
+= ~2000 lines of code
+```
+
+### With Facera
+```
+1 core definition + 3 facet files + 1 config
+= ~300 lines of code
+```
+
+**85% less code, 100% consistency guaranteed.**
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+gem install facera
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'facera'
+```
+
+### 1. Define Your Core
+
+```ruby
+# cores/payment_core.rb
+Facera.define_core(:payment) do
+  entity :payment do
+    attribute :id, :uuid, immutable: true
+    attribute :amount, :money, required: true
+    attribute :currency, :string, required: true
+    attribute :status, :enum, values: [:pending, :confirmed, :cancelled]
+    attribute :merchant_id, :uuid, required: true
+    attribute :customer_id, :uuid, required: true
+  end
+
+  capability :create_payment, type: :create do
+    entity :payment
+    requires :amount, :currency, :merchant_id, :customer_id
+    validates { amount > 0 }
+  end
+
+  capability :confirm_payment, type: :action do
+    entity :payment
+    requires :id
+    precondition { status == :pending }
+    transitions_to :confirmed
+  end
+end
+```
+
+### 2. Define Facets
+
+```ruby
+# facets/external_facet.rb
+Facera.define_facet(:external, core: :payment) do
+  description "Public API for external clients"
+
+  expose :payment do
+    fields :id, :amount, :currency, :status
+  end
+
+  allow_capabilities :create_payment
+end
+```
+
+```ruby
+# facets/internal_facet.rb
+Facera.define_facet(:internal, core: :payment) do
+  description "Service-to-service API"
+
+  expose :payment do
+    fields :all
+    computed :processing_time do |payment|
+      Time.now - payment.created_at
+    end
+  end
+
+  allow_capabilities :all
+end
+```
+
+### 3. Implement Business Logic
+
+Create an adapter to implement the actual logic:
+
+```ruby
+# adapters/payment_adapter.rb
+class PaymentAdapter
+  include Facera::Adapter
+
+  def create_payment(params)
+    # Your business logic here
+    Payment.create!(
+      amount: params[:amount],
+      currency: params[:currency],
+      merchant_id: params[:merchant_id],
+      customer_id: params[:customer_id],
+      status: :pending
+    )
+  end
+
+  def get_payment(params)
+    Payment.find(params[:id])
+  end
+
+  def confirm_payment(params)
+    payment = Payment.find(params[:id])
+    payment.update!(status: :confirmed, confirmed_at: Time.now)
+
+    # Send confirmation email
+    PaymentMailer.confirmation(payment).deliver_later
+
+    payment
+  end
+end
+```
+
+Or use inline blocks for simple logic:
+
+```ruby
+capability :simple_action, type: :action do
+  execute do |params|
+    # Simple inline logic
+    { result: "done" }
+  end
+end
+```
+
+### 4. Mount and Run
+
+```ruby
+# config.ru
+require 'facera'
+
+Facera.configure do |config|
+  config.base_path = '/api'
+  config.version = 'v1'
+end
+
+app = Rack::Builder.new do
+  Facera.auto_mount!(self)
+end
+
+run app
+```
+
+Start your server:
+
+```bash
+rackup -p 9292
+```
+
+**That's it!** You now have multiple APIs auto-generated:
+
+```bash
+# External API (limited fields)
+curl http://localhost:9292/api/v1/health
+curl -X POST http://localhost:9292/api/v1/payments \
+  -H 'Content-Type: application/json' \
+  -d '{"amount": 100.0, "currency": "USD", ...}'
+
+# Internal API (all fields + computed)
+curl http://localhost:9292/api/internal/v1/payments/:id
+
+# Introspection
+curl http://localhost:9292/api/facera/introspect
+curl http://localhost:9292/api/facera/openapi/external
+```
+
+---
+
+## Key Features
+
+- 💎 **Single Source of Truth** - Define domain model once
+- 🎭 **Multiple Facets** - Different views for different consumers
+- 🚀 **Auto-Generated APIs** - REST endpoints created automatically
+- 📦 **Zero Configuration** - Convention-based auto-discovery
+- 📚 **Built-in Introspection** - Explore your APIs at runtime
+- 📄 **OpenAPI Generation** - Auto-generated API documentation
+- 🔒 **Type Safety** - Strong typing for entities and capabilities
+- ✅ **Business Rules** - Invariants and validations in the core
+
+---
+
+## Documentation
+
+Comprehensive documentation available in the [wiki](https://github.com/jcagarcia/facera/wiki):
+
+- **[Core Concepts](https://github.com/jcagarcia/facera/wiki/Core-Concepts)** - Understanding cores, facets, and projections
+- **[Defining Cores](https://github.com/jcagarcia/facera/wiki/Defining-Cores)** - Entities, capabilities, and invariants
+- **[Defining Facets](https://github.com/jcagarcia/facera/wiki/Defining-Facets)** - Field visibility and capability access
+- **[Implementing Business Logic](https://github.com/jcagarcia/facera/wiki/Implementing-Business-Logic)** - Adapters and execute blocks
+- **[API Generation](https://github.com/jcagarcia/facera/wiki/API-Generation)** - Auto-generated REST endpoints
+- **[Auto-Mounting](https://github.com/jcagarcia/facera/wiki/Auto-Mounting)** - Convention-based discovery
+- **[Configuration](https://github.com/jcagarcia/facera/wiki/Configuration)** - Authentication, paths, and feature flags
+- **[Introspection](https://github.com/jcagarcia/facera/wiki/Introspection)** - Runtime introspection and OpenAPI
+- **[Deployment](https://github.com/jcagarcia/facera/wiki/Deployment)** - Production deployment guides
+- **[Architecture](https://github.com/jcagarcia/facera/wiki/Architecture)** - Design principles and framework integration
+- **[Examples](https://github.com/jcagarcia/facera/wiki/Examples)** - Complete working examples
+
+---
+
+## Example Structure
+
+```
+your_app/
+├── cores/
+│   └── payment_core.rb       # Domain model
+├── adapters/
+│   └── payment_adapter.rb    # Business logic
+├── facets/
+│   ├── external_facet.rb     # Public API
+│   ├── internal_facet.rb     # Service API
+│   └── operator_facet.rb     # Admin API
+└── config.ru                 # Rack config
+```
+
+Facera auto-discovers everything and generates:
+
+```
+GET  /api/v1/health
+POST /api/v1/payments
+GET  /api/v1/payments/:id
+
+GET  /api/internal/v1/health
+POST /api/internal/v1/payments
+GET  /api/internal/v1/payments/:id
+POST /api/internal/v1/payments/:id/confirm
+
+GET  /api/facera/introspect
+GET  /api/facera/cores
+GET  /api/facera/facets
+GET  /api/facera/openapi
+```
+
+---
+
+## Examples
+
+See the [examples/](examples/) directory for complete working examples:
+
+- **Phase Examples** - `01_core_dsl.rb` through `04_auto_mounting.rb`
+- **Runnable Server** - `examples/server/` with multiple facets
+
+Run the server:
+
+```bash
+cd examples/server
+rackup -p 9292
+```
+
+---
+
+## Contributing
+
+Contributions welcome! Please read [CONTRIBUTING.md](https://github.com/jcagarcia/facera/wiki/Contributing) for guidelines.
+
+```bash
+git clone https://github.com/yourusername/facera.git
+cd facera
+bundle install
+bundle exec rspec
+```
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details
+
+---
+
+## Credits
+
+Created by [Juan Carlos Garcia](https://github.com/jcagarcia)
+
+---
+
+**One semantic core. Multiple API facets. Zero duplication.**
+
+Start building better APIs today! 💎

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec