castkit 0.2.0 → 0.3.0

data/README.md

@@ -21,6 +21,8 @@ Castkit is designed to work seamlessly in service-oriented and API-driven archit
 - [DataObjects](#dataobjects)
 - [Contracts](#contracts)
 - [Advance Usage](#advanced-usage-coming-soon)
+- [Plugins](#plugins)
+- [Castkit CLI](#castkit-cli)
 - [Testing](#testing)
 - [Compatibility](#compatibility)
 - [License](#license)
@@ -58,14 +60,14 @@ Castkit comes with built-in support for primitive types and allows registration
 
 ```ruby
 {
-  array:    Castkit::Types::Collection,
-  boolean:  Castkit::Types::Boolean,
-  date:     Castkit::Types::Date,
-  datetime: Castkit::Types::DateTime,
-  float:    Castkit::Types::Float,
-  hash:     Castkit::Types::Generic,
-  integer:  Castkit::Types::Integer,
-  string:   Castkit::Types::String
+        array: Castkit::Types::Collection,
+        boolean: Castkit::Types::Boolean,
+        date: Castkit::Types::Date,
+        datetime: Castkit::Types::DateTime,
+        float: Castkit::Types::Float,
+        hash: Castkit::Types::Base,
+        integer: Castkit::Types::Integer,
+        string: Castkit::Types::String
 }
 ```
 
@@ -374,7 +376,8 @@ from_contract = Castkit::DataObject.from_contract(contract)
 To override default serialization behavior:
 
 ```ruby
-class CustomSerializer < Castkit::Serializer
+
+class CustomSerializer < Castkit::Serializers::Base
   def call
     { payload: object.to_h }
   end
@@ -427,7 +430,8 @@ end
 Or subclass directly:
 
 ```ruby
-class MyContract < Castkit::Contract::Generic
+
+class MyContract < Castkit::Contract::Base
   string :id
   integer :count, required: false
 end
@@ -532,7 +536,7 @@ UserContract.validate!(id: "abc", address: { city: "Boston" })
 
 Castkit is designed to be modular and extendable. Future guides will cover:
 
-- Custom serializers (`Castkit::Serializer`)
+- Custom serializers (`Castkit::Serializers::Base`)
 - Integration layers:
     - `castkit-activerecord` for syncing with ActiveRecord models
     - `castkit-msgpack` for binary encoding
@@ -543,6 +547,278 @@ Castkit is designed to be modular and extendable. Future guides will cover:
 
 ---
 
+## Plugins
+
+Castkit supports modular extensions through a lightweight plugin system. Plugins can modify or extend the behavior of `Castkit::DataObject` classes, such as adding serialization support, transformation helpers, or framework integrations.
+
+Plugins are just Ruby modules and can be registered and activated globally or per-class.
+
+---
+
+### 📦 Activating Plugins
+
+Plugins can be activated on any DataObject or at runtime:
+
+```ruby
+module MyPlugin
+  def self.setup!(klass)
+    # Optional: called after inclusion
+    klass.string :plugin_id
+  end
+
+  def plugin_feature
+    "Enabled!"
+  end
+end
+
+Castkit.configure do |config|
+  config.register_plugin(:my_plugin, MyPlugin)
+end
+
+class MyDto < Castkit::DataObject
+  Castkit::Plugins.activate(self, :my_plugin)
+end
+```
+
+This includes the `MyPlugin` module into `MyDto` and calls `MyPlugin.setup!(MyDto)` if defined.
+
+---
+
+### 🧩 Registering Plugins
+
+Plugins must be registered before use:
+
+```ruby
+Castkit.configure do |config|
+  config.register_plugin(:oj, Castkit::Plugins::Oj)
+end
+```
+
+You can then activate them:
+
+```ruby
+Castkit::Plugins.activate(MyDto, :oj)
+```
+
+---
+
+### 🧰 Plugin API
+
+| Method                        | Description |
+|------------------------------|-------------|
+| `Castkit::Plugins.register(:name, mod)` | Registers a plugin under a custom name. |
+| `Castkit::Plugins.activate(klass, *names)` | Includes one or more plugins into a class. |
+| `Castkit::Plugins.lookup!(:name)`        | Looks up the plugin by name or constant. |
+
+---
+
+### 📁 Plugin Structure
+
+Castkit looks for plugins under the `Castkit::Plugins` namespace by default:
+
+```ruby
+module Castkit
+  module Plugins
+    module Oj
+      def self.setup!(klass)
+        klass.include SerializationSupport
+      end
+    end
+  end
+end
+```
+
+To activate this:
+
+```ruby
+Castkit::Plugins.activate(MyDto, :oj)
+```
+
+You can also manually register plugins not under this namespace.
+
+---
+
+### ✅ Example Use Case
+
+```ruby
+module Castkit
+  module Plugins
+    module Timestamps
+      def self.setup!(klass)
+        klass.datetime :created_at
+        klass.datetime :updated_at
+      end
+    end
+  end
+end
+
+Castkit::Plugins.activate(UserDto, :timestamps)
+```
+
+This approach allows reusable, modular feature sets across DTOs with clean setup behavior.
+
+---
+
+## Castkit CLI
+
+Castkit includes a command-line interface to help scaffold and inspect DTO components with ease.
+
+The CLI is structured around two primary commands:
+
+- `castkit generate` — scaffolds boilerplate for Castkit components.
+- `castkit list` — introspects and displays registered or defined components.
+
+---
+
+## ✨ Generate Commands
+
+The `castkit generate` command provides subcommands for creating files for all core Castkit component types.
+
+### 🧱 DataObject
+
+```bash
+castkit generate dataobject User name:string age:integer
+```
+
+Creates:
+
+- `lib/castkit/data_objects/user.rb`
+- `spec/castkit/data_objects/user_spec.rb`
+
+### 📄 Contract
+
+```bash
+castkit generate contract UserInput id:string email:string
+```
+
+Creates:
+
+- `lib/castkit/contracts/user_input.rb`
+- `spec/castkit/contracts/user_input_spec.rb`
+
+### 🔌 Plugin
+
+```bash
+castkit generate plugin Oj
+```
+
+Creates:
+
+- `lib/castkit/plugins/oj.rb`
+- `spec/castkit/plugins/oj_spec.rb`
+
+### 🧪 Validator
+
+```bash
+castkit generate validator Money
+```
+
+Creates:
+
+- `lib/castkit/validators/money.rb`
+- `spec/castkit/validators/money_spec.rb`
+
+### 🧬 Type
+
+```bash
+castkit generate type money
+```
+
+Creates:
+
+- `lib/castkit/types/money.rb`
+- `spec/castkit/types/money_spec.rb`
+
+### 📦 Serializer
+
+```bash
+castkit generate serializer Json
+```
+
+Creates:
+
+- `lib/castkit/serializers/json.rb`
+- `spec/castkit/serializers/json_spec.rb`
+
+You can disable test generation with `--no-spec`.
+
+---
+
+## 📋 List Commands
+
+The `castkit list` command provides an interface to view internal Castkit definitions or project-registered components.
+
+### 🧾 List Types
+
+```bash
+castkit list types
+```
+
+Displays a grouped list of:
+
+- Native types (defined by Castkit)
+- Custom types (registered via `Castkit.configure`)
+
+Example:
+
+```bash
+Native Types:
+  Castkit::Types::String         - :string, :str, :uuid
+
+Custom Types:
+  MyApp::Types::Money            - :money
+```
+
+### 🔍 List Validators
+
+```bash
+castkit list validators
+```
+
+Displays all validator classes defined in `lib/castkit/validators` or custom-defined under `Castkit::Validators`.
+
+Castkit validators are tagged `[Castkit]`, and others as `[Custom]`.
+
+### 📑 List Contracts
+
+```bash
+castkit list contracts
+```
+
+Lists all contracts in the `Castkit::Contracts` namespace and related files.
+
+### 📦 List DataObjects
+
+```bash
+castkit list dataobjects
+```
+
+Lists all DTOs in the `Castkit::DataObjects` namespace.
+
+### 🧪 List Serializers
+
+```bash
+castkit list serializers
+```
+
+Lists all serializer classes and their source origin.
+
+---
+
+## 🧰 Example Usage
+
+```bash
+castkit generate dataobject Product name:string price:float
+castkit generate contract ProductInput name:string
+
+castkit list types
+castkit list validators
+```
+
+The CLI is designed to provide a familiar Rails-like generator experience, tailored for Castkit’s data-first architecture.
+
+---
+
 ## Testing
 
 You can test DTOs and Contracts by treating them like plain Ruby objects:

data/castkit.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
+  spec.add_dependency "thor"
 
   # Development dependencies
   spec.add_development_dependency "rspec"

data/lib/castkit/castkit.rb

@@ -20,12 +20,15 @@ require_relative "inflector"
 # @see Castkit::Contract
 # @see Castkit::DataObject
 module Castkit
-  # Namespace used for registering DataObjects generated from contracts.
+  # Namespace used for registering generated DataObjects.
   module DataObjects; end
 
-  # Namespace used for registering contracts generated from DataObjects.
+  # Namespace used for registering generated contracts.
   module Contracts; end
 
+  # Namespace used for registering generated plugins.
+  module Plugins; end
+
   class << self
     # Yields the global configuration object for customization.
     #

data/lib/castkit/cli/generate.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../../generators/contract"
+require_relative "../../generators/data_object"
+require_relative "../../generators/plugin"
+require_relative "../../generators/serializer"
+require_relative "../../generators/type"
+require_relative "../../generators/validator"
+
+module Castkit
+  module CLI
+    # Thor CLI class for generating Castkit components.
+    #
+    # Provides `castkit generate` commands for each major Castkit component, including types,
+    # data objects, contracts, validators, serializers, and plugins.
+    #
+    # All generators support the `--no-spec` flag to skip spec file creation.
+    class Generate < Thor
+      desc "contract NAME", "Generates a new Castkit contract"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new contract class.
+      #
+      # @param name [String] the class name for the contract
+      # @param fields [Array<String>] optional attribute definitions
+      # @return [void]
+      def contract(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Contract.start(args)
+      end
+
+      desc "dataobject NAME", "Generates a new Castkit DataObject"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new DataObject class.
+      #
+      # @param name [String] the class name for the data object
+      # @param fields [Array<String>] optional attribute definitions
+      # @return [void]
+      def dataobject(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::DataObject.start(args)
+      end
+
+      desc "plugin NAME", "Generates a new Castkit plugin"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new plugin module.
+      #
+      # @param name [String] the module name for the plugin
+      # @param fields [Array<String>] optional stub fields
+      # @return [void]
+      def plugin(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Plugin.start(args)
+      end
+
+      desc "serializer NAME", "Generates a new Castkit serializer"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new custom serializer class.
+      #
+      # @param name [String] the class name for the serializer
+      # @param fields [Array<String>] optional stub fields
+      # @return [void]
+      def serializer(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Serializer.start(args)
+      end
+
+      desc "type NAME", "Generates a new Castkit type"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new custom type.
+      #
+      # @param name [String] the class name for the type
+      # @return [void]
+      def type(name)
+        args = [Castkit::Inflector.pascalize(name)]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Type.start(args)
+      end
+
+      desc "validator NAME", "Generates a new Castkit validator"
+      method_option :spec, type: :boolean, default: true
+      # Generates a new validator class.
+      #
+      # @param name [String] the class name for the validator
+      # @param fields [Array<String>] optional stub fields
+      # @return [void]
+      def validator(name, *fields)
+        args = [Castkit::Inflector.pascalize(name), fields]
+        args << "--no-spec" unless options[:spec]
+        Castkit::Generators::Validator.start(args)
+      end
+    end
+  end
+end

data/lib/castkit/cli/list.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "thor"
+require "castkit"
+require_relative "../../generators/contract"
+require_relative "../../generators/data_object"
+require_relative "../../generators/plugin"
+require_relative "../../generators/serializer"
+require_relative "../../generators/type"
+require_relative "../../generators/validator"
+
+module Castkit
+  module CLI
+    # CLI commands for listing internal Castkit registry components.
+    #
+    # Supports listing:
+    # - Registered types (`castkit list types`)
+    # - Available validators (`castkit list validators`)
+    #
+    # @example Show all available types
+    #   $ castkit list types
+    #
+    # @example Show all defined validators
+    #   $ castkit list validators
+    class List < Thor
+      desc "types", "Lists registered Castkit types"
+      # Lists registered Castkit types, grouped into native and custom-defined.
+      #
+      # @return [void]
+      def types
+        all_keys = Castkit.configuration.types
+        default_keys = Castkit::Configuration::DEFAULT_TYPES.keys
+
+        native_types(all_keys, default_keys)
+        custom_types(all_keys, default_keys)
+      end
+
+      desc "contracts", "Lists all generated Castkit contracts"
+      # Lists all Castkit contract classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def contracts
+        list_files("contracts")
+      end
+
+      desc "dataobjects", "Lists all generated Castkit DataObjects"
+      # Lists all Castkit DataObjects classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def dataobjects
+        list_files("data_objects")
+      end
+
+      desc "serializers", "Lists all generated Castkit serializers"
+      # Lists all Castkit serializers classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def serializers
+        list_files("serializers")
+      end
+
+      desc "validators", "Lists all generated Castkit validators"
+      # Lists all Castkit validator classes defined in the file system or registered under the Castkit namespace.
+      #
+      # @return [void]
+      def validators
+        list_files("validators")
+      end
+
+      private
+
+      # Prints all native types and their aliases.
+      #
+      # @param all_types [Hash<Symbol, Object>] all registered types
+      # @param default_keys [Array<Symbol>] predefined native type keys
+      # @return [void]
+      def native_types(all_types, default_keys)
+        alias_map = reverse_grouped(Castkit::Configuration::TYPE_ALIASES)
+        native = all_types.slice(*default_keys)
+
+        say "Native Types:", :green
+        native.each do |name, type|
+          aliases = alias_map[name] || []
+          list_type(type.class, [name, *aliases].map(&:to_sym))
+        end
+      end
+
+      # Prints all custom (non-native, non-alias) registered types.
+      #
+      # @param all_types [Hash<Symbol, Object>]
+      # @param default_keys [Array<Symbol>]
+      # @return [void]
+      def custom_types(all_types, default_keys)
+        alias_keys = Castkit::Configuration::TYPE_ALIASES.keys.map(&:to_sym)
+        custom = all_types.except(*default_keys).reject { |k, _| alias_keys.include?(k) }
+
+        say "\nCustom Types:", :green
+        return no_custom_types if custom.empty?
+
+        grouped_custom_types(custom)
+      end
+
+      # Outputs a fallback message if no custom types exist.
+      #
+      # @return [void]
+      def no_custom_types
+        say "  No registered types, register with " \
+            "#{set_color("Castkit.configure { |c| c.register_type(:type, Type) }", :yellow)}"
+      end
+
+      # Groups and prints custom types by their class.
+      #
+      # @param types [Hash<Symbol, Object>]
+      # @return [void]
+      def grouped_custom_types(types)
+        types.group_by { |_, inst| inst.class }.each do |klass, group|
+          list_type(klass, group.map(&:first).map(&:to_sym))
+        end
+      end
+
+      # Reverses a hash of alias => type into type => [aliases].
+      #
+      # @param hash [Hash]
+      # @return [Hash{Symbol => Array<Symbol>}]
+      def reverse_grouped(hash)
+        hash.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(k, v), acc|
+          acc[v] << k
+        end
+      end
+
+      # Prints a type or class with all its symbol aliases.
+      #
+      # @param klass [Class]
+      # @param keys [Array<Symbol>]
+      # @return [void]
+      def list_type(klass, keys)
+        types = keys.uniq.sort.map { |k| set_color(":#{k}", :yellow) }.join(", ")
+        say "  #{(klass.name || "<AnonymousType>").ljust(34)} - #{types}"
+      end
+
+      # Lists class references for a component (e.g. validators), distinguishing by source (file or custom).
+      #
+      # @param component [String] base namespace (e.g. "validators")
+      # @return [void]
+      def list_files(component)
+        path = "lib/castkit/#{component}"
+        all_classes, file_classes = component_classes(component, path)
+        return say "No registered #{Castkit::Inflector.pascalize(component)} found." if all_classes.empty?
+
+        max_width = all_classes.map(&:length).max + 5
+        say "Castkit #{Castkit::Inflector.pascalize(component)}", :green
+
+        all_classes.each do |klass|
+          tag = file_classes.include?(klass) ? set_color("[Castkit]", :yellow) : set_color("[Custom]", :green)
+          say "  #{klass.ljust(max_width)} #{tag}"
+        end
+      end
+
+      # Gathers all registered and defined constants for a component.
+      #
+      # @param component [String]
+      # @param path [String]
+      # @return [Array<[Array<String>, Set<String>]>]
+      def component_classes(component, path)
+        namespace = Castkit.const_get(Castkit::Inflector.pascalize(component))
+        file_classes = file_classes(namespace, path)
+        defined_classes = defined_classes(namespace)
+
+        all_classes = (file_classes + defined_classes).to_a.sort
+        [all_classes, file_classes]
+      end
+
+      # Converts file names into class names for a given component.
+      #
+      # @param namespace [Module]
+      # @param path [String]
+      # @return [Set<String>]
+      def file_classes(namespace, path)
+        classes = Dir.glob("#{path}/*.rb")
+                     .map { |f| File.basename(f, ".rb") }
+                     .reject { |f| f.to_s == "base" }
+                     .map { |base| "#{namespace}::#{Castkit::Inflector.pascalize(base)}" }
+
+        classes.to_set
+      end
+
+      # Lists actual constants under a namespace, filtering out missing definitions.
+      #
+      # @param namespace [Module]
+      # @return [Set<String>]
+      def defined_classes(namespace)
+        namespace.constants
+                 .reject { |const| const.to_s == "Base" }
+                 .map { |const| "#{namespace}::#{const}" }
+                 .select { |klass| Object.const_defined?(klass) }
+                 .to_set
+      end
+    end
+  end
+end

data/lib/castkit/cli/main.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "generate"
+require_relative "list"
+
+module Castkit
+  module CLI
+    # Main CLI entry point for Castkit.
+    #
+    # Provides top-level commands for printing the gem version and generating Castkit components.
+    #
+    # @example Print the version
+    #   $ castkit version
+    #
+    # @example Generate a DataObject
+    #   $ castkit generate dataobject User name:string age:integer
+    class Main < Thor
+      desc "version", "Prints the version"
+      # Outputs the current Castkit version.
+      #
+      # @return [void]
+      def version
+        puts Castkit::VERSION
+      end
+
+      desc "generate TYPE NAME", "Generate a Castkit component"
+      # Dispatches to the `castkit generate` subcommands.
+      #
+      # Supports generating components like `type`, `dataobject`, `contract`, etc.
+      #
+      # @return [void]
+      subcommand "generate", Castkit::CLI::Generate
+
+      desc "list COMPONENT", "List registered Castkit components"
+      # Dispatches to the `castkit list` subcommands.
+      #
+      # Supports listing components like `type`, `dataobject`, `contract`, etc.
+      #
+      # @return [void]
+      subcommand "list", Castkit::CLI::List
+    end
+  end
+end