agentcode 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 156884253ac38e8338ed1a4dd25f0d6b07b490159981cf527a82767dd753a78c
+  data.tar.gz: 38425ac745bee34c114409082f47823d0bee5f0024b42ebc67e86f8c97f4cbd1
+SHA512:
+  metadata.gz: 4826283c4e629c65742f910b2d53a5714e816830c7bcaefcfb305a88c75d825c03981d71390e2ee10290deea83de55244d4e6ec94e0f23d4dd3e1ee563661573
+  data.tar.gz: ee02e159498fc5e3c21467dea7e83ea3c20aa2b85ffea5b23b3ce061f212582d042a22fa9c0952bc3099f87631c045905e5c15e557a2b00e32be6bfdb29b3c94

data/README.md

@@ -0,0 +1,59 @@
+# AgentCode — Rails
+
+> Automatic REST API generation for Rails models with built-in security, validation, and advanced querying.
+
+[![Ruby](https://img.shields.io/badge/ruby-3.1%2B-red)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-7%2B-red)](https://rubyonrails.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Register a model, get a full REST API instantly.
+
+## Features
+
+| # | Feature | Description |
+|---|---------|-------------|
+| 1 | **Automatic CRUD Endpoints** | Generates `index`, `show`, `create`, `update`, `destroy` for every registered model. |
+| 2 | **Authentication** | Login, logout, password recovery/reset, invitation-based registration. |
+| 3 | **Authorization & Policies** | Pundit-based permission checks (`{slug}.{action}`), wildcard support. |
+| 4 | **Role-Based Access Control** | Per-org roles via `user_roles` join table. |
+| 5 | **Attribute-Level Permissions** | Control which fields each role can read and write. |
+| 6 | **Validation** | Dual-layer: format rules + field presence. Supports role-keyed rules. |
+| 7 | **Cross-Tenant FK Validation** | `exists:` rules auto-scoped to current org, even through indirect FK relationships. |
+| 8 | **Filtering** | `?filter[field]=value` with AND/OR logic. |
+| 9 | **Sorting** | `?sort=-created_at,title` — ascending and descending. |
+| 10 | **Full-Text Search** | `?search=term` across configured fields, supports relationship dot notation. |
+| 11 | **Pagination** | Header-based metadata (`X-Current-Page`, `X-Last-Page`, `X-Per-Page`, `X-Total`). |
+| 12 | **Field Selection** | `?fields[posts]=id,title,status` to reduce payload. |
+| 13 | **Eager Loading** | `?include=user,comments` with nested, Count/Exists suffixes, and auth per include. |
+| 14 | **Multi-Tenancy** | Organization-based data isolation, auto-set `organization_id`, global scope. |
+| 15 | **Nested Ownership** | Auto-detects org by walking `belongs_to` chains. |
+| 16 | **Route Groups** | Multiple URL prefixes with different middleware/auth (`tenant`, `public`, custom). |
+| 17 | **Soft Deletes** | Discard gem — trash, restore, force-delete endpoints with individual permissions. |
+| 18 | **Audit Trail** | Logs all CRUD events with old/new values, user, IP, and org context. |
+| 19 | **Nested Operations** | `POST /nested` for atomic multi-model transactions with `$N.field` references. |
+| 20 | **Invitations** | Token-based invite system with create, resend, cancel, accept, and role assignment. |
+| 21 | **Hidden Columns** | Base + model-level + policy-level dynamic column hiding per role. |
+| 22 | **Auto-Scope Discovery** | Auto-registers scopes by naming convention. |
+| 23 | **UUID Primary Keys** | `HasUuid` concern for auto-generated UUIDs. |
+| 24 | **Middleware Support** | Global per model + per action middleware. |
+| 25 | **Action Exclusion** | `except_actions` to disable specific CRUD routes. |
+| 26 | **Generator CLI** | `agentcode:install`, `agentcode:generate`, `agentcode:blueprint`, `agentcode:export_postman`. |
+| 27 | **Postman Export** | Auto-generated Postman Collection v2.1 with all endpoints. |
+| 28 | **Blueprint System** | YAML-to-code generation for models, migrations, factories, policies, tests, and seeders. |
+
+## Quick Start
+
+```bash
+bundle add agentcode
+rails agentcode:install
+```
+
+## Documentation
+
+For full documentation, guides, and API reference visit:
+
+**[https://startsoft-dev.github.io/agentcode-docs/docs/getting-started](https://startsoft-dev.github.io/agentcode-docs/docs/getting-started)**
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

data/lib/agentcode/blueprint/blueprint_parser.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "digest"
+
+module AgentCode
+  module Blueprint
+    # Parses YAML blueprint files into normalized data structures.
+    # Port of agentcode-server BlueprintParser.php / agentcode-adonis-server blueprint_parser.ts.
+    class BlueprintParser
+      # Parse _roles.yaml file into normalized role definitions.
+      #
+      # @param file_path [String]
+      # @return [Hash<String, Hash>] e.g. { 'owner' => { name: 'Owner', description: '...' } }
+      def parse_roles(file_path)
+        content = read_file(file_path)
+
+        raise "Blueprint roles file is empty: #{file_path}" if content.strip.empty?
+
+        parsed = begin
+          YAML.safe_load(content, permitted_classes: [Symbol])
+        rescue Psych::SyntaxError
+          raise "Invalid YAML syntax in: #{file_path}"
+        end
+
+        raise "Invalid YAML structure in: #{file_path}" unless parsed.is_a?(Hash)
+        raise "Missing 'roles' key in: #{file_path}" unless parsed["roles"]
+
+        roles = {}
+
+        parsed["roles"].each do |slug, value|
+          raise "Invalid role definition for '#{slug}' — expected a hash" unless value.is_a?(Hash)
+
+          roles[slug] = {
+            name: value["name"] || slug_to_name(slug),
+            description: value["description"] || ""
+          }
+        end
+
+        roles
+      end
+
+      # Parse a model blueprint YAML file into normalized structure.
+      #
+      # @param file_path [String]
+      # @return [Hash] ParsedBlueprint hash
+      def parse_model(file_path)
+        content = read_file(file_path)
+
+        raise "Blueprint file is empty: #{file_path}" if content.strip.empty?
+
+        parsed = begin
+          YAML.safe_load(content, permitted_classes: [Symbol])
+        rescue Psych::SyntaxError
+          raise "Invalid YAML syntax in: #{file_path}"
+        end
+
+        raise "Invalid YAML structure in: #{file_path}" unless parsed.is_a?(Hash)
+        raise "Missing 'model' key in: #{file_path}" unless parsed["model"]
+
+        model_name = parsed["model"]
+        slug = parsed["slug"] || model_to_slug(model_name)
+        table = parsed["table"] || slug
+
+        source_file = File.basename(file_path)
+
+        {
+          model: model_name,
+          slug: slug,
+          table: table,
+          options: normalize_options(parsed["options"] || {}),
+          columns: normalize_columns(parsed["columns"] || {}),
+          relationships: parsed["relationships"] || [],
+          permissions: normalize_permissions(parsed["permissions"] || {}),
+          source_file: source_file
+        }
+      end
+
+      # Compute SHA-256 hash of a file's contents.
+      #
+      # @param file_path [String]
+      # @return [String] 64-char hex hash
+      def compute_file_hash(file_path)
+        Digest::SHA256.hexdigest(File.read(file_path))
+      end
+
+      # ──────────────────────────────────────────────
+      # Normalization helpers
+      # ──────────────────────────────────────────────
+
+      def normalize_options(options)
+        {
+          belongs_to_organization: options.fetch("belongs_to_organization", false),
+          soft_deletes: options.fetch("soft_deletes", true),
+          audit_trail: options.fetch("audit_trail", false),
+          owner: options.fetch("owner", nil),
+          except_actions: options.fetch("except_actions", []),
+          pagination: options.fetch("pagination", false),
+          per_page: options.fetch("per_page", 25)
+        }
+      end
+
+      def normalize_columns(columns)
+        result = []
+
+        columns.each do |name, value|
+          if value.is_a?(String)
+            # Short syntax: field_name: type
+            result << {
+              name: name,
+              type: value,
+              nullable: false,
+              unique: false,
+              index: false,
+              default: nil,
+              filterable: false,
+              sortable: false,
+              searchable: false,
+              precision: nil,
+              scale: nil,
+              foreign_model: nil
+            }
+          elsif value.is_a?(Hash)
+            result << {
+              name: name,
+              type: value.fetch("type", "string"),
+              nullable: value.fetch("nullable", false),
+              unique: value.fetch("unique", false),
+              index: value.fetch("index", false),
+              default: value.fetch("default", nil),
+              filterable: value.fetch("filterable", false),
+              sortable: value.fetch("sortable", false),
+              searchable: value.fetch("searchable", false),
+              precision: value.fetch("precision", nil),
+              scale: value.fetch("scale", nil),
+              foreign_model: value.fetch("foreign_model", nil)
+            }
+          end
+        end
+
+        result
+      end
+
+      def normalize_permissions(permissions)
+        result = {}
+
+        permissions.each do |role, value|
+          next unless value.is_a?(Hash)
+
+          result[role] = {
+            actions: value["actions"] || [],
+            show_fields: normalize_field_list(value["show_fields"]),
+            create_fields: normalize_field_list(value["create_fields"]),
+            update_fields: normalize_field_list(value["update_fields"]),
+            hidden_fields: normalize_field_list(value["hidden_fields"])
+          }
+        end
+
+        result
+      end
+
+      def normalize_field_list(value)
+        return [] if value.nil?
+        return ["*"] if value == "*"
+        return [value] if value.is_a?(String)
+        return value if value.is_a?(Array)
+
+        []
+      end
+
+      private
+
+      def read_file(file_path)
+        File.read(file_path)
+      rescue Errno::ENOENT
+        raise "File not found or unreadable: #{file_path}"
+      end
+
+      def slug_to_name(slug)
+        slug.split("_").map(&:capitalize).join(" ")
+      end
+
+      def model_to_slug(model_name)
+        # PascalCase → snake_case plural
+        snake = model_name.gsub(/([A-Z])/, '_\1').downcase.sub(/\A_/, "")
+
+        # Simple pluralization
+        if snake.end_with?("y") && !snake.match?(/[aeiou]y\z/)
+          snake[0..-2] + "ies"
+        elsif snake.match?(/(s|x|z|ch|sh)\z/)
+          snake + "es"
+        else
+          snake + "s"
+        end
+      end
+    end
+  end
+end

data/lib/agentcode/blueprint/blueprint_validator.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module AgentCode
+  module Blueprint
+    # Validates parsed blueprint data structures.
+    # Port of agentcode-server BlueprintValidator.php / agentcode-adonis-server blueprint_validator.ts.
+    class BlueprintValidator
+      VALID_COLUMN_TYPES = %w[
+        string text integer bigInteger boolean date datetime
+        timestamp decimal float json uuid foreignId
+      ].freeze
+
+      VALID_ACTIONS = %w[
+        index show store update destroy trashed restore forceDelete
+      ].freeze
+
+      # Validate role definitions.
+      #
+      # @param roles [Hash<String, Hash>]
+      # @return [Hash] { valid:, errors: }
+      def validate_roles(roles)
+        errors = []
+
+        if roles.empty?
+          errors << "At least one role is required"
+          return { valid: false, errors: errors }
+        end
+
+        roles.each do |slug, role|
+          unless slug.match?(/\A[a-z][a-z0-9_]*\z/)
+            errors << "Invalid role slug '#{slug}' — must match /^[a-z][a-z0-9_]*$/"
+          end
+
+          if role[:name].nil? || role[:name].strip.empty?
+            errors << "Role '#{slug}' must have a non-empty name"
+          end
+        end
+
+        { valid: errors.empty?, errors: errors }
+      end
+
+      # Validate a full model blueprint.
+      #
+      # @param blueprint [Hash]
+      # @param valid_roles [Hash] optional role definitions for cross-reference
+      # @return [Hash] { valid:, errors:, warnings: }
+      def validate_model(blueprint, valid_roles = {})
+        errors = []
+        warnings = []
+
+        # Model name
+        if blueprint[:model].nil? || blueprint[:model].strip.empty?
+          errors << "Model name is required"
+        elsif !blueprint[:model].match?(/\A[A-Z][a-zA-Z0-9]*\z/)
+          errors << "Invalid model name '#{blueprint[:model]}' — must be PascalCase (match /^[A-Z][a-zA-Z0-9]*$/)"
+        end
+
+        # Columns
+        errors.concat(validate_columns(blueprint[:columns]))
+
+        # Permissions
+        column_names = blueprint[:columns].map { |c| c[:name] }
+        perm_result = validate_permissions(blueprint[:permissions], valid_roles, column_names)
+        errors.concat(perm_result[:errors])
+        warnings.concat(perm_result[:warnings])
+
+        # Options
+        errors.concat(validate_options(blueprint[:options]))
+
+        # Relationships
+        errors.concat(validate_relationships(blueprint[:relationships]))
+
+        { valid: errors.empty?, errors: errors, warnings: warnings }
+      end
+
+      # Validate columns.
+      #
+      # @param columns [Array<Hash>]
+      # @return [Array<String>] errors
+      def validate_columns(columns)
+        errors = []
+        seen = Set.new
+
+        columns.each do |col|
+          if col[:name].nil? || col[:name].strip.empty?
+            errors << "Column name is required"
+            next
+          end
+
+          if seen.include?(col[:name])
+            errors << "Duplicate column name '#{col[:name]}'"
+          end
+          seen.add(col[:name])
+
+          unless VALID_COLUMN_TYPES.include?(col[:type])
+            errors << "Invalid column type '#{col[:type]}' for column '#{col[:name]}'"
+          end
+
+          if col[:type] == "foreignId" && col[:foreign_model].nil?
+            errors << "Column '#{col[:name]}' is foreignId but missing 'foreign_model'"
+          end
+        end
+
+        errors
+      end
+
+      # Validate permissions.
+      #
+      # @return [Hash] { errors:, warnings: }
+      def validate_permissions(permissions, valid_roles, column_names)
+        errors = []
+        warnings = []
+        has_roles = !valid_roles.empty?
+
+        permissions.each do |role, perm|
+          # Check role exists
+          if has_roles && !valid_roles.key?(role)
+            errors << "Unknown role '#{role}' in permissions"
+          end
+
+          # Check actions
+          perm[:actions].each do |action|
+            unless VALID_ACTIONS.include?(action)
+              errors << "Invalid action '#{action}' for role '#{role}'"
+            end
+          end
+
+          # Check field references
+          all_column_names = ["id"] + column_names
+          check_field_references(perm[:show_fields], all_column_names, role, "show_fields", warnings)
+          check_field_references(perm[:create_fields], all_column_names, role, "create_fields", warnings)
+          check_field_references(perm[:update_fields], all_column_names, role, "update_fields", warnings)
+
+          # Warn on conflicts
+          if perm[:hidden_fields].any? && perm[:show_fields].any?
+            perm[:hidden_fields].each do |field|
+              if perm[:show_fields].include?(field)
+                warnings << "Role '#{role}': field '#{field}' is in both show_fields and hidden_fields"
+              end
+            end
+          end
+
+          # Warn on create_fields without store action
+          if perm[:create_fields].any? && !perm[:create_fields].include?("*") &&
+             perm[:create_fields].any? { |f| f != "*" } && !perm[:actions].include?("store")
+            warnings << "Role '#{role}': has create_fields but no 'store' action"
+          end
+
+          # Warn on update_fields without update action
+          if perm[:update_fields].any? && !perm[:update_fields].include?("*") &&
+             perm[:update_fields].any? { |f| f != "*" } && !perm[:actions].include?("update")
+            warnings << "Role '#{role}': has update_fields but no 'update' action"
+          end
+        end
+
+        { errors: errors, warnings: warnings }
+      end
+
+      # Validate options.
+      def validate_options(options)
+        errors = []
+
+        if options[:except_actions]
+          options[:except_actions].each do |action|
+            unless VALID_ACTIONS.include?(action)
+              errors << "Invalid action '#{action}' in except_actions"
+            end
+          end
+        end
+
+        errors
+      end
+
+      # Validate relationships.
+      def validate_relationships(relationships)
+        errors = []
+        valid_types = %w[belongsTo hasMany hasOne belongsToMany]
+
+        relationships.each do |rel|
+          rel = rel.transform_keys(&:to_s) if rel.is_a?(Hash)
+
+          if rel["type"].nil?
+            errors << "Relationship is missing type"
+          elsif !valid_types.include?(rel["type"])
+            errors << "Invalid relationship type '#{rel["type"]}'"
+          end
+
+          if rel["model"].nil?
+            errors << "Relationship is missing model"
+          end
+        end
+
+        errors
+      end
+
+      private
+
+      def check_field_references(fields, column_names, role, field_key, warnings)
+        return if fields.empty? || (fields.length == 1 && fields[0] == "*")
+
+        fields.each do |field|
+          if field != "*" && !column_names.include?(field)
+            warnings << "Role '#{role}': unknown field '#{field}' in #{field_key}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agentcode/blueprint/generators/factory_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module AgentCode
+  module Blueprint
+    module Generators
+      # Generates FactoryBot factory files with smart Faker detection.
+      # Reuses faker mapping logic from GenerateCommand.
+      class FactoryGenerator
+        # Generate a FactoryBot factory file.
+        #
+        # @param blueprint [Hash] ParsedBlueprint
+        # @return [String] Ruby source code
+        def generate(blueprint)
+          model_name = blueprint[:model]
+          factory_name = model_name.underscore
+          columns = blueprint[:columns]
+
+          field_lines = columns.map do |col|
+            next if col[:name] == "organization_id" && blueprint[:options][:belongs_to_organization]
+
+            if col[:type] == "foreignId" || col[:type] == "references"
+              if col[:foreign_model]
+                relation = col[:name].sub(/_id\z/, "")
+                "    association :#{relation}, factory: :#{col[:foreign_model].underscore}"
+              else
+                "    #{col[:name]} { Faker::Number.between(from: 1, to: 10) }"
+              end
+            else
+              "    #{col[:name]} { #{column_to_faker(col)} }"
+            end
+          end.compact
+
+          <<~RUBY
+            # frozen_string_literal: true
+
+            FactoryBot.define do
+              factory :#{factory_name} do
+            #{field_lines.join("\n")}
+              end
+            end
+          RUBY
+        end
+
+        private
+
+        def column_to_faker(column)
+          case column[:name]
+          when "name", "full_name" then "Faker::Name.name"
+          when "email" then "Faker::Internet.email"
+          when "title" then "Faker::Lorem.sentence(word_count: 3)"
+          when "description", "content", "body" then "Faker::Lorem.paragraph"
+          when "slug" then "Faker::Internet.slug"
+          when "phone", "phone_number" then "Faker::PhoneNumber.phone_number"
+          when "url", "website" then "Faker::Internet.url"
+          when /\Ais_/ then "[true, false].sample"
+          else
+            case column[:type]
+            when "string" then "Faker::Lorem.sentence(word_count: 3)"
+            when "text" then "Faker::Lorem.paragraph"
+            when "integer", "bigInteger" then "Faker::Number.between(from: 1, to: 100)"
+            when "boolean" then "[true, false].sample"
+            when "date" then "Faker::Date.between(from: 1.year.ago, to: Date.today)"
+            when "datetime", "timestamp" then "Faker::Time.between(from: 1.year.ago, to: Time.current)"
+            when "decimal", "float" then "Faker::Number.decimal(l_digits: 3, r_digits: 2)"
+            when "json" then "{}"
+            when "uuid" then "SecureRandom.uuid"
+            else "Faker::Lorem.word"
+            end
+          end
+        end
+      end
+    end
+  end
+end