hati-rails-api 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1402a4d0cd8d1aad576c25e026eabe7f59a4124f3263e8d709a5badb35666249
+  data.tar.gz: ef4cfd0e3e3d791692607b8be6223dd371d0ce1184914ca3ce524f2ee05053e8
+SHA512:
+  metadata.gz: e57aa35cd26e896573e65ccaf2396eb275b9d8ce1ab9c68473f06439e0ec4f548b650c6411044880fa234007ec9e74512756529110b26f5b55c6da2fde055df2
+  data.tar.gz: f56b6a32a3f7d96000873df30e27180d04d8a6a94211fc69840af6845814f174e3867503eb67c019343aeb18bf53e1a5b8715ced60fdff5fb159e058b3ed6b31

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hackico.ai
+
+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,237 @@
+# Hati Rails API
+
+A high-performance, scalable toolkit for building robust, domain-driven Rails APIs with migration-style code generation, clean architecture, and agentic/AI-ready patterns.
+
+## What is Hati Rails API?
+
+Hati Rails API is a Ruby gem that brings **migration-style, pattern-based code generation** to Rails APIs. It enables:
+
+- **Domain-driven design** with clear context boundaries
+- **Clean, SOLID architecture** for maintainable codebases
+- **Fast, repeatable development** with migration files and rollback
+- **Agentic/AI-ready workflows**: all code generation is explicit, declarative, and context-driven—perfect for automation and large-scale projects
+
+## Framework Components & How They Work Together
+
+### Context System
+
+Centralizes domain logic, boundaries, and code generation. You define “contexts” (domains) in migration files. Each context can have operations, endpoints, models, and any number of custom layers (service, query, validation, serializer, etc.).
+
+### Migration Engine
+
+Provides a migration-style, repeatable, and rollbackable way to define and evolve your API structure. Migration files (class-based or DSL) describe what to generate. Running migrations creates or updates code; rollbacks revert changes.
+
+### Generator
+
+Orchestrates the actual file generation, tracking, and rollback. Reads migration files, generates code (models, controllers, operations, etc.), and tracks what was created for safe rollback.
+
+### Layer System
+
+Supports modular, extensible architecture. Built-in layers include:
+
+- **Operation:** Business logic, step-based or simple
+- **Service:** Application services, integrations
+- **Query:** Data access/query objects
+- **Validation:** Input/business validation
+- **Serializer:** Output formatting
+- **Custom:** Add your own (analytics, repository, etc.)
+
+### ResponseHandler
+
+Standardizes API responses and error handling. Controllers include this module to automatically handle operation results, errors, and JSON:API formatting.
+
+### Rollback Manager
+
+Enables safe, timestamped rollback of generated code. Tracks every file generated by a migration. Rollbacks remove files and clean up empty directories.
+
+### Macro System
+
+Provides reusable code patterns and metaprogramming helpers. Macros can be used in operations, layers, or anywhere in the context system to DRY up code and enforce patterns.
+
+### Error Handling
+
+Centralizes error types and handling logic. Custom error classes for unsupported operations, configuration issues, and more. Integrated with ResponseHandler for clean API error responses.
+
+### Versioning
+
+Tracks the version of the Hati Rails API gem. Ensures agents and humans know which features and patterns are available.
+
+**How They Work Together:**
+
+- You define your API’s structure and patterns in migration files.
+- The Migration Engine and Generator read these files, using the Layer System to create all necessary code (operations, models, controllers, etc.).
+- ResponseHandler ensures all endpoints behave consistently.
+- Rollback Manager lets you safely undo changes, supporting rapid, iterative, and agent-driven development.
+- Macros and Error Handling provide reusable patterns and robust error management.
+- Versioning ensures compatibility and traceability.
+
+The result is a highly modular, pattern-driven, and automation-friendly Rails API framework—ready for both human and AI/agentic development at scale.
+
+## Quick Start
+
+### 1. Install the Gem
+
+Add to your Gemfile:
+
+```ruby
+gem 'hati-rails-api'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### 2. Initialize the Context System
+
+```bash
+rails generate hati_rails_api:context init
+```
+
+This creates:
+
+- `config/contexts.rb` (global config)
+- `config/contexts/` (migration files go here)
+- `app/contexts/` (generated code)
+
+### 3. Create a Migration File
+
+Generate a migration for a domain:
+
+```bash
+rails generate hati_rails_api:context user --operations=create,update,delete
+```
+
+Edit the generated file in `config/contexts/` to define your domain, operations, and layers.
+
+### 4. Run Migrations
+
+Generate all code from migrations:
+
+```bash
+rails generate hati_rails_api:context run --force
+```
+
+### 5. Rollback (if needed)
+
+```bash
+rails generate hati_rails_api:context rollback --timestamp=YOUR_TIMESTAMP
+```
+
+## Basic Usage Example
+
+A migration file (class-based, AI/agentic-ready):
+
+```ruby
+# config/contexts/20250721001327_create_user_context.rb
+class CreateUserContext < HatiRailsApi::Context::Migration
+  def change
+    domain :user do |domain|
+      domain.operation do |operation|
+        operation.component [:create, :update, :delete]
+      end
+      domain.endpoint true
+      domain.model true
+      domain.validation
+      domain.query
+      domain.service
+      domain.serializer
+    end
+    model [:user, :user_token]
+    endpoint [:user_status]
+  end
+end
+
+CreateUserContext.new.run
+```
+
+This will generate:
+
+- Operations: `app/contexts/user/operation/create_operation.rb`, etc.
+- Controller: `app/controllers/api/user_controller.rb`
+- Models: `app/models/user.rb`, `app/models/user_token.rb`
+- Additional layers: `app/contexts/user/validation/`, `query/`, `service/`, `serializer/`
+
+## Advanced Usage & Patterns
+
+### Granular/Agentic Steps
+
+You can use granular steps to patternize operation logic based on other layers:
+
+```ruby
+domain.operation do |operation|
+  operation.component [:authenticate, :authorize]
+  operation.step true, granular: true # Will use all other domain layers as steps
+end
+```
+
+### Custom Layers
+
+Add any custom layer to your domain:
+
+```ruby
+domain.analytics do |analytics|
+  analytics.component [:event_tracker, :report_generator]
+end
+```
+
+### Explicit Steps
+
+```ruby
+domain.operation do |operation|
+  operation.component [:register]
+  operation.step :validate, :persist, :notify
+end
+```
+
+### Full Example: Scalable, AI-Ready Context
+
+```ruby
+class CreateEcommerceContext < HatiRailsApi::Context::Migration
+  def change
+    domain :ecommerce do |domain|
+      domain.operation do |operation|
+        operation.component [:checkout, :refund]
+        operation.step true, granular: true
+      end
+      domain.endpoint true
+      domain.model true
+      domain.validation { |v| v.component [:payment_validator] }
+      domain.query { |q| q.component [:order_finder] }
+      domain.service { |s| s.component [:payment_gateway] }
+      domain.analytics { |a| a.component [:sales_reporter] }
+    end
+    model [:order, :payment]
+    endpoint [:order_status]
+  end
+end
+
+CreateEcommerceContext.new.run
+```
+
+## Library Architecture & Extensibility
+
+- **Migration-Driven**: All code generation is declarative and repeatable
+- **Layered**: Add/remove layers as your architecture evolves
+- **Rollbackable**: Every generation is tracked and can be reverted
+- **Composable**: Use as building blocks for agentic/AI workflows
+- **Extensible**: Add new layer types, code templates, or DSL methods
+
+## Why Hati Rails API for AI/Agentic Development?
+
+- **Patternization**: All code is generated from explicit, context-rich patterns
+- **Automation-Ready**: Migrations are just Ruby—easy to generate, modify, or analyze with AI agents
+- **Scalable**: Designed for large, fast-moving teams and projects
+- **Robust**: Rollback, test, and iterate safely
+- **Clear Examples**: Every migration is a living, executable example
+
+## Wrap Up
+
+Hati Rails API brings the power of migration-driven, pattern-based, and agentic development to Rails APIs. Use it to:
+
+- Rapidly scaffold and evolve complex API architectures
+- Automate code generation with AI/agentic tools
+- Maintain clean, robust, and scalable codebases
+
+**For more examples, documentation, and advanced patterns, see the [project repo](https://github.com/hackico-ai/hati-rails-api).**

data/hati-rails-api.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'hati_rails_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'hati-rails-api'
+  spec.version = HatiRailsApi::VERSION
+  spec.authors = ['Mariya Giy', 'Yuri Gi']
+  spec.email   = ['giy.mariya@gmail.com', 'yurigi.pro@gmail.com']
+  spec.license = 'MIT'
+
+  spec.summary     = 'A Rails API tool for building API services.'
+  spec.description = 'A Rails API tool for building API services.'
+  spec.homepage    = "https://github.com/hackico-ai/#{spec.name}"
+
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.files  = Dir['CHANGELOG.md', 'LICENSE', 'README.md', 'hati-rails-api.gemspec', 'lib/**/*']
+  spec.bindir = 'bin'
+  spec.executables   = []
+  spec.require_paths = ['lib']
+
+  spec.metadata['repo_homepage']     = spec.homepage
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['changelog_uri']   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.add_dependency 'hati-operation'
+  spec.add_dependency 'hati-jsonapi-error'
+  spec.add_dependency 'railties', '>= 6.0'
+end

data/lib/generators/hati_rails_api/context_generator.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/base'
+
+module HatiRailsApi
+  module Generators
+    # Rails generator for HatiRailsApi context operations
+    # Provides Rails integration for the context system with migration-style workflow
+    class ContextGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      argument :command, type: :string, default: 'init',
+                         desc: 'Command: init, run, rollback, list, or domain name for quick generation'
+
+      class_option :force, type: :boolean, default: false,
+                           desc: 'Force overwrite existing files'
+
+      class_option :timestamp, type: :string,
+                               desc: 'Timestamp for rollback operation'
+
+      class_option :operations, type: :array, default: [],
+                                desc: 'Operations to generate for the domain'
+
+      class_option :endpoint, type: :boolean, default: true,
+                              desc: 'Generate API endpoint for the domain'
+
+      def perform_command
+        case command.downcase
+        when 'init', 'initialize'
+          initialize_context
+        when 'run', 'execute'
+          run_migrations
+        when 'rollback', 'rb'
+          rollback_generation
+        when 'list', 'ls'
+          list_generations
+        else
+          # Treat as domain name for migration creation
+          create_domain_migration(command)
+        end
+      end
+
+      private
+
+      def initialize_context
+        say 'Initializing HatiRailsApi Context System...', :green
+        create_configuration_files
+        create_directory_structure
+        create_example_migration
+        say "\nContext system initialized successfully!", :green
+        say 'Check the generated files and examples to get started.', :blue
+        say "\nMigration-style workflow:", :yellow
+        say '  1. rails generate hati_rails_api:context user        # Create domain migration'
+        say '  2. rails generate hati_rails_api:context run         # Execute migrations'
+        say '  3. rails generate hati_rails_api:context rollback    # Rollback last'
+        say '  4. rails generate hati_rails_api:context list        # Show generations'
+      end
+
+      def create_domain_migration(domain_name)
+        say "Creating migration for domain: #{domain_name}", :green
+        timestamp = Time.now.strftime('%Y%m%d%H%M%S')
+        migration_file = "config/contexts/#{timestamp}_create_#{domain_name}_context.rb"
+        operations = if options[:operations].any?
+                       options[:operations].flat_map { |op| op.split(',') }.map(&:strip)
+                     else
+                       ['create', 'update', 'destroy']
+                     end
+        endpoint_enabled = options[:endpoint]
+        create_file migration_file, domain_migration_template(domain_name, operations, endpoint_enabled)
+        say "Migration created: #{migration_file}", :green
+        say 'Edit the migration file to customize the domain configuration', :blue
+        say 'Run: rails generate hati_rails_api:context run', :yellow
+      end
+
+      def run_migrations
+        say 'Running context migrations...', :green
+        migration_files = Dir[Rails.root.join('config', 'contexts', '*_create_*_context.rb')].sort
+        if migration_files.empty?
+          say_error 'No context migrations found!'
+          say 'Create a domain migration first: rails generate hati_rails_api:context user'
+          return
+        end
+        require_context_system
+        configure_defaults unless HatiRailsApi::Context.configured?
+        executed_count = 0
+        migration_files.each do |migration_file|
+          executed_count += 1 if execute_migration(migration_file)
+        end
+        if executed_count > 0
+          say "Successfully executed #{executed_count} migration(s)!", :green
+          say 'Use --force to override all existing files without prompting', :yellow unless options[:force]
+        else
+          say 'No new migrations to execute', :blue
+        end
+      end
+
+      def execute_migration(migration_file)
+        say "Executing: #{File.basename(migration_file)}", :yellow
+        begin
+          require_context_system
+          configure_defaults unless HatiRailsApi::Context.configured?
+          migration_content = File.read(migration_file)
+          if migration_content.include?('< HatiRailsApi::Context::Migration')
+            load migration_file
+          else
+            HatiRailsApi::Context.generate(force: options[:force]) do |ctx|
+              ctx.instance_eval(migration_content, migration_file)
+            end
+          end
+          say "Completed: #{File.basename(migration_file)}", :green
+          true
+        rescue StandardError => e
+          say_error "Error executing #{File.basename(migration_file)}: #{e.message}"
+          say_error "Location: #{e.backtrace&.first}"
+          false
+        end
+      end
+
+      def rollback_generation
+        say 'Rolling back generation...', :yellow
+        require_context_system
+        result = if options[:timestamp]
+                   HatiRailsApi::Context.rollback(options[:timestamp])
+                 else
+                   HatiRailsApi::Context.rollback
+                 end
+        if result
+          say 'Rollback completed successfully!', :green
+        else
+          say_error 'Rollback failed!'
+        end
+      end
+
+      def list_generations
+        say 'Listing all generations...', :blue
+        require_context_system
+        HatiRailsApi::Context.list_generations
+      end
+
+      def create_configuration_files
+        create_file 'config/contexts.rb', global_config_template
+        create_file 'config/contexts/.gitkeep', ''
+      end
+
+      def create_directory_structure
+        empty_directory 'app/contexts'
+        create_file 'app/contexts/.gitkeep', ''
+      end
+
+      def create_example_migration
+        timestamp = Time.now.strftime('%Y%m%d%H%M%S')
+        create_file "config/contexts/#{timestamp}_create_example_context.rb", example_migration_template
+      end
+
+      def require_context_system
+        require File.expand_path('../../hati_rails_api/context', __dir__)
+      end
+
+      def configure_defaults
+        HatiRailsApi::Context.configure do |config|
+          config.base_path 'app/contexts'
+          config.model path: 'app/models', base: 'ApplicationRecord'
+          config.endpoint path: 'app/controllers/api', base: 'ApplicationController'
+        end
+      end
+
+      def global_config_template
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # HatiRailsApi Global Context Configuration
+          # This file contains global settings for the context system
+
+          require 'hati_rails_api/context'
+
+          # Configure global settings
+          HatiRailsApi::Context.configure do |config|
+            config.base_path 'app/contexts'
+            config.model path: 'app/models', base: 'ApplicationRecord'
+            config.endpoint path: 'app/controllers/api', base: 'ApplicationController'
+          end
+
+          # Global domain configuration (applies to all domains)
+          HatiRailsApi::Context.configure do |config|
+            config.domain do |domain|
+              # Default operation layer with common base
+              domain.operation do |operation|
+                operation.base 'hati_operation/base'
+              end
+            end
+          end
+        RUBY
+      end
+
+      def domain_migration_template(domain_name, operations, endpoint_enabled)
+        operation_list = operations.map(&:to_sym).inspect
+        timestamp = Time.now.strftime('%Y%m%d%H%M%S')
+        class_name = "Create#{domain_name.camelize}Context"
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Context Migration: Create #{domain_name.camelize} Domain
+          # Generated at #{Time.now}
+
+          class #{class_name} < HatiRailsApi::Context::Migration
+            def change
+              domain :#{domain_name} do |domain|
+                # Define operations for this domain
+                domain.operation do |operation|
+                  operation.component #{operation_list}
+                end
+                # API endpoint configuration
+                domain.endpoint #{endpoint_enabled}
+                # Optional: Add custom layers
+                # domain.validation do |validation|
+                #   validation.component [:input_validator, :business_validator]
+                # end
+                # domain.query do |query|
+                #   query.component [:finder, :searcher]
+                # end
+                # domain.service do |service|
+                #   service.component [:mailer, :notifier]
+                # end
+                # domain.serializer do |serializer|
+                #   serializer.component [:json_serializer, :xml_serializer]
+                # end
+              end
+              # Optional: Generate domain-specific models
+              # model [:#{domain_name}]
+              # Optional: Generate additional endpoints
+              # endpoint [:#{domain_name}_status]
+            end
+          end
+
+          #{class_name}.new.run
+        RUBY
+      end
+
+      def example_migration_template
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Example Context Migration
+          # This is an example - you can safely delete this file
+
+          # ctx.domain :ecommerce do |domain|
+          #   domain.operation do |operation|
+          #     operation.component [:payment_processing, :inventory_management, :order_fulfillment]
+          #   end
+          #   domain.endpoint enabled: true
+          #   domain.service do |service|
+          #     service.component [:notification, :analytics]
+          #   end
+          #   domain.query do |query|
+          #     query.component [:product_finder, :order_searcher]
+          #   end
+          # end
+
+          # ctx.model [:product, :order, :customer]
+          # ctx.endpoint [:health, :metrics]
+        RUBY
+      end
+
+      def say_error(message)
+        say message, :red
+      end
+    end
+  end
+end

data/lib/hati_rails_api/context/configuration/configuration.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative 'domain_configuration'
+
+module HatiRailsApi
+  module Context
+    # Main configuration class for the context system
+    # Follows Single Responsibility Principle - handles global configuration
+    class Configuration
+      attr_accessor :model_config, :endpoint_config, :domain_config
+
+      def initialize
+        @base_path = 'app/contexts'
+        @model_config = { path: 'app/models', base: 'ApplicationRecord' }
+        @endpoint_config = { path: 'app/controllers/api', base: 'ApplicationController' }
+        @domain_config = DomainConfiguration.new
+      end
+
+      def base_path(path = nil)
+        return @base_path unless path
+
+        @base_path = path
+      end
+
+      def model(path: nil, base: nil)
+        @model_config.merge!(path: path) if path
+        @model_config.merge!(base: base) if base
+        @model_config
+      end
+
+      def endpoint(enabled = true, **options)
+        return @endpoint_config unless enabled || !options.empty?
+
+        case enabled
+        when false
+          @endpoint_config = { enabled: false }
+        when Hash
+          @endpoint_config.merge!(enabled)
+        else
+          @endpoint_config.merge!(options)
+        end
+      end
+
+      def domain(&block)
+        @domain_config.instance_eval(&block) if block_given?
+        @domain_config
+      end
+    end
+  end
+end

data/lib/hati_rails_api/context/configuration/domain_configuration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative '../shared/layer_factory'
+
+module HatiRailsApi
+  module Context
+    # Domain-specific configuration class
+    # Follows Single Responsibility Principle - handles domain layer configuration
+    class DomainConfiguration
+      include LayerFactory
+
+      DEFAULT_DOMAIN_STATE = { enabled: false }.freeze
+
+      attr_reader :layers
+
+      def initialize
+        @layers = {}
+      end
+
+      def operation(&block)
+        @layers[:operation] = create_operation_layer(&block)
+      end
+
+      def layer(layer_name, &block)
+        @layers[layer_name.to_sym] = create_standard_layer(layer_name, &block)
+      end
+
+      def endpoint(enabled: true, **options)
+        @domain_endpoint = create_endpoint_state(enabled, options)
+      end
+
+      def method_missing(method_name, ...)
+        result = create_dynamic_layer(method_name, ...)
+        return super unless result
+
+        @layers[method_name.to_sym] = result
+      end
+
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
+      end
+
+      private
+
+      def create_endpoint_state(enabled, options)
+        case enabled
+        when false then DEFAULT_DOMAIN_STATE
+        when true  then { enabled: true, options: options, explicit_components: nil }
+        when Array then { enabled: true, options: options, explicit_components: enabled }
+        when Hash  then { enabled: true, options: enabled, explicit_components: nil }
+        end
+      end
+    end
+  end
+end