foobara 0.0.125 → 0.0.127

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff16e115901fed01d02a1d3a82cb136672b4f2a903f4d982311a38ea03f711d3
-  data.tar.gz: 206a0ea46c89ca30e036b9400870a237574cfac44783f3931e03eba1918bb06a
+  metadata.gz: 531c75e332f6e7cc297b0b56689d91f59737040fe533814a8b780defc937b2aa
+  data.tar.gz: 16dd8725423abe9155c1fd5b89c752271ce568ec83cca52c7654204ee114f559
 SHA512:
-  metadata.gz: d0ca391c67892c58ac22452c084a4f7ce8f0de5b7fbfff756f57faa0ce822df2ef2786d3818c44871267203a9b323e5a89b810404d26508b29e9eb7ac6dc3b38
-  data.tar.gz: 1dfc1aa32f61a7b832dd29cb0d3a966fc38bd2908a146ca208dcb9aadaab9880beb07efd4256cb57b820e3b2982aff37f98c4ecea6bb5a31bd1a3fcfaa217e0d
+  metadata.gz: 9c97ed1f00a114ea3ff8e1932cb32a13e8e538b1a0dc694f542060febafcae9e515e4888695cdbeede192e490ea280e6bddf8bf54b64e6339fe7adeaaeaa42a1
+  data.tar.gz: 4e414afd9090bc83685ce1b2e30fb31948963f4d57cff4d77ba4aa698547e716fd5a562442845f60cd8e6affb06263797fcf0c539a7f5478fceb9dec6b1412de

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [0.0.127] - 2025-05-25
+
+- Add better support for using ruby classes as types
+- Support using :attributes as a type directly
+- Make TransformedCommand#inputs reflect actual received inputs not transformed inputs
+- Add NestedTransactionable.with_needed_transactions_for_type
+
+# [0.0.126] - 2025-05-21
+
+- Fix bugs with transactions, Command.depends_on
+- Allow anonymous commands
+- Add CommandConnector#all_exposed_type_names
+
 # [0.0.125] - 2025-05-15
 
 - Create a yaml inputs sugar

data/README.md

@@ -1,6 +1,9 @@
-Foobara is a software framework with a focus on projects that have
-a complicated business domain. It accomplishes this by helping to
-build projects that are command-centric and discoverable, as well as some other features that aid in the mission.
+Foobara is a software framework to help you encapsulate your high-level
+domain operations in commands, and automatically expose machine-readable formal metadata about those
+commands so that integration code can be decoupled and abstracted away.
+
+This, as well as some other features of foobara, help manage domain complexity and produce
+more flexible systems with better management of domain complexity.
 
 You can watch a video that gives a good overview of what Foobara is and its goals here:
 [Introduction to the Foobara software framework](https://youtu.be/SSOmQqjNSVY)
@@ -24,6 +27,7 @@ You can watch a video that gives a good overview of what Foobara is and its goal
       * [HTTP Command Connectors](#http-command-connectors)
         * [Rack Connector](#rack-connector)
         * [Rails Connector](#rails-connector)
+    * [MCP Command Connector](#mcp-command-connector)
       * [Async Command Connectors](#async-command-connectors)
       * [Scheduler Command Connectors](#scheduler-command-connectors)
   * [Intermediate Foobara](#intermediate-foobara)
@@ -51,6 +55,7 @@ You can watch a video that gives a good overview of what Foobara is and its goal
     * [Namespaces](#namespaces)
     * [Value processors](#value-processors)
 * [Additional learning materials/Documentation](#additional-learning-materialsdocumentation)
+* [Help](#help)
 * [Contributing](#contributing)
   * [Developing locally](#developing-locally)
   * [Monorepo Structure](#monorepo-structure)
@@ -67,7 +72,7 @@ You can watch a video that gives a good overview of what Foobara is and its goal
 
 ## Discoverability
 
-* This means there is a formal machine-readable description of the systems/subsystems
+* This means there is a formal, machine-readable, description of the systems/subsystems
 * The implication of this is that integration code can be abstracted away.
 
 ## Implications of command-centric + discoverability
@@ -75,6 +80,7 @@ You can watch a video that gives a good overview of what Foobara is and its goal
 * The system better communicates the mental model of the problem and the chosen solution
 * Engineers are able to spend more time writing code relevant to the domain and less time
   writing code related to specific tech-stack, software pattern, or architecture decisions.
+* Engineers are much less likely to harmfully couple domain logic to integration logic.
 * Engineers can spend more time operating within a specific mental model at a time instead of
   multiple mental models all at once.
 
@@ -86,14 +92,14 @@ You can watch a video that gives a good overview of what Foobara is and its goal
   * Domains are namespaces of Commands, types, and errors
     * Domains (and commands) have explicit, unidirectional dependencies on other domains
   * Organizations are namespaces of Domains
-* Domain mappers
-  * These can map a concept from one domain to another
-  * This separation of concerns leads to commands that have code
-    that reflects the domain they belong to as opposed to logic from many different domains
 * Remote commands
   * These have the same interface as commands that live in other systems and act as a proxy to them
   * This allows rearchitecting of systems without changing interfaces and so reducing refactoring/testing required
   * These currently exist for both Ruby and Typescript
+* Domain mappers
+  * These can map a concept from one domain to another
+  * This separation of concerns leads to commands that have code
+    that reflects the domain they belong to as opposed to logic from many different domains
 * Code generators
   * Similar to remote commands, discoverability enables other types of tooling, including code generators,
     documentation tools, etc
@@ -107,8 +113,6 @@ You can watch a video that gives a good overview of what Foobara is and its goal
 # Installation
 
 To add foobara to an existing project, you can add `foobara` gem to your Gemfile or .gemspec as you normally would.
-You can also `gem install foobara` and whatever additional foobara gems you need and use them in
-scripts by requiring them.
 
 You could also use a generator to create a new Ruby Foobara project using the `foob` gem with `gem install foob` and
 then run `foob generate ruby-project --name your-org/your-new-project-name`
@@ -344,7 +348,7 @@ We have so far seen one Foobara type which is `integer` but there are many other
 We used :integer to type the operands of our Add command. There are many ways to express types in Foobara
 but in this case we used the attributes DSL. It has the form:
 
-`<attribute_naem> <type_symbol> [processors] [description]`
+`<attribute_name> <type_symbol> [processors] [description]`
 
 We used a processor `:required` but there are many others and you can create your own.
 
@@ -830,6 +834,67 @@ end
 
 This has the same effect as the previous code and is just a stylistic alternative.
 
+### MCP Command Connector
+
+We can have an MCP server for free for our commands. Let's try it!
+
+Let's simulate some bad data and expose some commands over MCP and ask an
+MCP client like Claude Code to find/fix the bad data.
+
+```ruby
+CreateCapybara.run!(name: "Fumiko", year_of_birth: 2020)
+# Simulate a year accidentally entered with a 2-digit format where a 4-digit format was expected:
+CreateCapybara.run!(name: "Barbara", year_of_birth: 19)
+CreateCapybara.run!(name: "Basil", year_of_birth: 2021)
+
+mcp_connector = Foobara::McpConnector.new
+
+mcp_connector.connect(FindAllCapybaras)
+mcp_connector.connect(UpdateCapybara)
+
+mcp_connector.run_stdio_server
+```
+
+Oh whoops, somebody entered Barbara's year of birth as 19 instead of 2019, whoops!
+Let's ask Claude Code to find/fix the bad record: 
+
+```
+$ claude
+> Hi! There's a Capybara whose birth year was entered incorrectly. Can you find which one
+  and fix it? Thanks!
+● I'll help find and fix the capybara with the incorrect birth year. Let me search for the
+  capybaras first.
+● mcp-test:FindAllCapybaras (MCP)()…
+  ⎿  [
+       {
+         "name": "Fumiko",
+         "year_of_birth": 2020,
+         "id": 1
+
+     … +7 lines (ctrl+r to expand)
+
+         "name": "Basil",
+         "year_of_birth": 2021,
+         "id": 3
+       }
+     ]
+● It looks like Barbara (id 2) has an incorrect birth year of 19, which is too low. Let me
+  fix that to 2019.
+● mcp-test:UpdateCapybara (MCP)(id: 2, year_of_birth: 2019)…
+  ⎿  {
+       "name": "Barbara",
+       "year_of_birth": 2019,
+       "id": 2
+     }
+● Fixed! Barbara's birth year has been updated from 19 to 2019.
+> Great! Thanks!
+● You're welcome!
+```
+Record fixed! A benefit of encapsulating your high-level domain operations behind commands that have machine-readable
+formal manifests describing them is easy tooling like this.
+
+See https://github.com/foobara/mcp-connector for details on how to do this if interested. 
+
 #### Async Command Connectors
 
 Let's connect a command to some sort of async job solution. We'll connect our IncrementAge command to Resque:
@@ -2041,17 +2106,19 @@ TODO: give some code examples
   * All docs combined: https://docs.foobara.com/all/
   * Per-repository docs: https://foobara.com/docs
 
-# Contributing
+# Help
 
-Probably a good idea to reach out if you'd like to contribute code or documentation or other
-forms of help. We could pair on what you have in mind and you could drive or at least we can make sure
-it's a good use of time. I can be reached at azimux@gmail.com
+Are you actually trying to build something with Foobara? Happy to help! miles@foobara.com
 
-You can contribute via a github pull request as is typical
+# Contributing
 
-Make sure the test suite and linter pass locally before opening a pull request
+There are many ways you could help! There are tasks in the codebase for all skill levels including absolute beginner.
+There's also much need for improved documentation. If you're interested in helping but don't know how, then
+please reach out! miles@foobara.com
 
-The build will fail if test coverage is below 100%
+You are welcome to also contribute via a github pull request or open issues for bugs. 
+Make sure the test suite and linter pass locally before opening a pull request as 
+the build will fail if test coverage is below 100%.
 
 ## Developing locally
 
@@ -2068,7 +2135,7 @@ And if the tests/linter pass then you could dive into modifying the code
 
 ## Monorepo Structure
 
-Foobara is split up into many projects
+Foobara is split up into many, many projects
 
 Many are in separate repositories which you can see at: https://github.com/orgs/foobara/repositories
 

data/projects/builtin_types/src/attributes/supported_transformers/defaults/type_declaration_extension/extend_attributes_type_declaration/desugarizers/move_defaults_from_element_types_to_root.rb

@@ -8,7 +8,7 @@ module Foobara
               module Desugarizers
                 class MoveDefaultsFromElementTypesToRoot < TypeDeclarations::Desugarizer
                   def applicable?(value)
-                    value.is_a?(::Hash) && value[:type] == :attributes
+                    value.is_a?(::Hash) && value[:type] == :attributes && value.key?(:element_type_declarations)
                   end
 
                   def desugarize(rawish_type_declaration)

data/projects/builtin_types/src/attributes/supported_validators/required/type_declaration_extension/extend_attributes_type_declaration/desugarizers/move_required_from_element_types_to_root.rb

@@ -8,7 +8,7 @@ module Foobara
               module Desugarizers
                 class MoveRequiredFromElementTypesToRoot < TypeDeclarations::Desugarizer
                   def applicable?(value)
-                    value.is_a?(::Hash) && value[:type] == :attributes
+                    value.is_a?(::Hash) && value[:type] == :attributes && value.key?(:element_type_declarations)
                   end
 
                   def desugarize(rawish_type_declaration)

data/projects/builtin_types/src/duck/supported_validators/instance_of/type_declaration_extension/extend_registered_type_declaration/desugarizers/class_type_desugarizer.rb

@@ -0,0 +1,32 @@
+module Foobara
+  module BuiltinTypes
+    module Duck
+      module SupportedValidators
+        class InstanceOf < TypeDeclarations::Validator
+          module TypeDeclarationExtension
+            module ExtendRegisteredTypeDeclaration
+              module Desugarizers
+                class ClassTypeDesugarizer < TypeDeclarations::Desugarizer
+                  def applicable?(rawish_type_declaration)
+                    return false unless rawish_type_declaration.is_a?(::Hash)
+
+                    rawish_type_declaration[:type].is_a?(::Class)
+                  end
+
+                  def desugarize(rawish_type_declaration)
+                    klass = rawish_type_declaration[:type]
+                    rawish_type_declaration.merge(type: :duck, instance_of: klass.name)
+                  end
+
+                  def priority
+                    Priority::LOWEST + 1
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/duck/supported_validators/instance_of.rb

@@ -14,6 +14,16 @@ module Foobara
             end
           end
 
+          class << self
+            def requires_parent_declaration_data?
+              true
+            end
+          end
+
+          def applicable?(value)
+            !value.nil? || !parent_declaration_data[:allow_nil]
+          end
+
           def expected_class_name
             declaration_data
           end

data/projects/command/src/command/concerns/shortcut_for_run.rb

@@ -19,6 +19,8 @@ module Foobara
 
         module ClassMethods
           def define_command_named_function
+            return if name.nil?
+
             command_class = self
             convenience_method_name = Foobara::Util.non_full_name(command_class)
             containing_module = Foobara::Util.module_for(command_class) || Object

data/projects/command/src/command_pattern_implementation/concerns/inputs.rb

@@ -31,8 +31,6 @@ module Foobara
           inputs_type&.element_types&.key?(method_name)
         end
 
-        foobara_delegate :inputs_type, to: :class
-
         def cast_and_validate_inputs
           if inputs_type.nil? && (raw_inputs.nil? || raw_inputs.empty?)
             @inputs = {}

data/projects/command/src/command_pattern_implementation/concerns/runtime.rb

@@ -67,7 +67,8 @@ module Foobara
         end
 
         def run_execute
-          result = process_result_using_result_type(execute)
+          raw_result = execute
+          result = process_result_using_result_type(raw_result)
           @outcome = Outcome.success(result)
         end
 

data/projects/command/src/command_pattern_implementation/concerns/subcommands.rb

@@ -65,6 +65,8 @@ module Foobara
                             else
                               superclass.depends_on.dup
                             end
+
+              return @depends_on
             end
 
             if subcommand_classes.length == 1

data/projects/command_connectors/src/command_connector.rb

@@ -644,5 +644,10 @@ module Foobara
 
       command_registry.foobara_all_command(mode: Namespace::LookupMode::ABSOLUTE)
     end
+
+    def all_exposed_type_names
+      # TODO: cache this or better yet cache #foobara_manifest
+      foobara_manifest[:type].keys.sort.map(&:to_s)
+    end
   end
 end

data/projects/command_connectors/src/transformed_command.rb

@@ -578,6 +578,7 @@ module Foobara
     def run
       apply_allowed_rule
       apply_pre_commit_transformers
+      set_inputs
       run_command
       # this gives us primary keys
       flush_transactions
@@ -609,6 +610,22 @@ module Foobara
                                 end
     end
 
+    def inputs
+      return @inputs if defined?(@inputs)
+
+      @inputs = if inputs_type
+                  outcome = inputs_type.process_value(untransformed_inputs)
+
+                  if outcome.success?
+                    outcome.result
+                  else
+                    untransformed_inputs
+                  end
+                else
+                  {}
+                end
+    end
+
     def transform_result
       if self.class.result_transformer
         self.outcome = Outcome.success(self.class.result_transformer.process_value!(result))
@@ -723,6 +740,14 @@ module Foobara
       end
     end
 
+    def set_inputs
+      if self.class.inputs_type
+        command.after_cast_and_validate_inputs do |**|
+          inputs
+        end
+      end
+    end
+
     def run_command
       outcome = command.run
       self.outcome = outcome if outcome

data/projects/detached_entity/src/concerns/associations.rb

@@ -187,7 +187,7 @@ module Foobara
                 construct_associations(element_type, path.append(:"#"), result, initial: false)
               end
             elsif type.extends?(BuiltinTypes[:attributes]) # TODO: matches attributes itself instead of only subtypes
-              type.element_types.each_pair do |attribute_name, element_type|
+              type.element_types&.each_pair do |attribute_name, element_type|
                 if remove_sensitive && element_type.sensitive?
                   next
                 end

data/projects/domain_mapper/src/domain_mapper_lookups.rb

@@ -89,9 +89,9 @@ module Foobara
 
         unless strict
           if from
-            lookup_matching_domain_mapper(from: nil, to:)
+            lookup_matching_domain_mapper(from: nil, to:, criteria:)
           elsif to
-            lookup_matching_domain_mapper(from:, to: nil)
+            lookup_matching_domain_mapper(from:, to: nil, criteria:)
           end
         end
       end

data/projects/model/src/extensions/type_declarations/handlers/extend_registered_model_type_declaration.rb

@@ -10,6 +10,7 @@ module Foobara
             type_symbol = strict_type_declaration[:type]
 
             return false if type_symbol == expected_type_symbol
+            return false unless type_symbol.is_a?(::Symbol) || type_symbol.is_a?(::String)
 
             if type_registered?(type_symbol)
               type = lookup_type!(type_symbol)

data/projects/nested_transactionable/lib/foobara/nested_transactionable.rb

@@ -17,6 +17,33 @@ module Foobara
 
         entity_classes.uniq
       end
+
+      def with_needed_transactions_for_type(type, &)
+        relevant_entity_classes = relevant_entity_classes_for_type(type)
+
+        if relevant_entity_classes.empty?
+          return yield
+        end
+
+        tx_class = Class.new
+        tx_class.include NestedTransactionable
+
+        tx_class.define_method(:relevant_entity_classes) do
+          relevant_entity_classes
+        end
+
+        tx_instance = tx_class.new
+
+        begin
+          tx_instance.open_transaction
+          result = Persistence::EntityBase.using_transactions(tx_instance.transactions, &)
+          tx_instance.commit_transaction
+          result
+        rescue
+          tx_instance.rollback_transaction
+          raise
+        end
+      end
     end
 
     def relevant_entity_classes_for_type(type)
@@ -45,7 +72,10 @@ module Foobara
 
       bases.each do |base|
         tx = base.current_transaction
-        transactions << tx if tx
+
+        if tx&.open?
+          transactions << tx
+        end
       end
     end
 

data/projects/type_declarations/src/handlers/extend_attributes_type_declaration/hash_desugarizer.rb

@@ -17,7 +17,8 @@ module Foobara
             type_symbol = sugary_type_declaration[:type]
 
             if [:attributes, "attributes"].include?(type_symbol)
-              Util.all_symbolizable_keys?(sugary_type_declaration[:element_type_declarations])
+              sugary_type_declaration.key?(:element_type_declarations) &&
+                Util.all_symbolizable_keys?(sugary_type_declaration[:element_type_declarations])
             elsif type_symbol.is_a?(::Symbol)
               # Why is this done?
               !type_registered?(type_symbol)

data/projects/type_declarations/src/handlers/extend_attributes_type_declaration/to_type_transformer.rb

@@ -9,7 +9,7 @@ module Foobara
           def transform(strict_type_declaration)
             super.tap do |type|
               type_declarations = type.declaration_data[:element_type_declarations]
-              type.element_types = type_declarations.transform_values do |attribute_declaration|
+              type.element_types = type_declarations&.transform_values do |attribute_declaration|
                 type_for_declaration(attribute_declaration)
               end
             end

data/projects/type_declarations/src/handlers/registered_type_declaration.rb

@@ -13,7 +13,9 @@ module Foobara
           # we only handle case where it's a builtin type not an extension of one
           if strict_type_declaration.keys == [:type]
             type_symbol = strict_type_declaration[:type]
-            type_registered?(type_symbol)
+            if type_symbol.is_a?(::Symbol) || type_symbol.is_a?(::String)
+              type_registered?(type_symbol)
+            end
           end
         end
 

data/projects/types/src/type.rb

@@ -35,7 +35,7 @@ module Foobara
                   :element_type
 
       def initialize(
-        *,
+        declaration_data,
         target_classes:,
         base_type:,
         description: nil,
@@ -52,10 +52,12 @@ module Foobara
         sensitive_exposed: nil,
         **opts
       )
+        self.declaration_data = declaration_data
         self.sensitive = sensitive
         self.sensitive_exposed = sensitive_exposed
         self.base_type = base_type
         self.description = description
+        self.name = name
         self.casters = [*casters, *base_type&.casters]
         self.transformers = [*transformers, *base_type&.transformers]
         self.validators = [*validators, *base_type&.validators]
@@ -65,11 +67,10 @@ module Foobara
         # TODO: combine these maybe with the term "children_types"?
         self.element_types = element_types
         self.element_type = element_type
-        self.name = name
         self.target_classes = Util.array(target_classes)
         self.processor_classes_requiring_type = processor_classes_requiring_type
 
-        super(*, **opts.merge(processors:, prioritize: false))
+        super(declaration_data, **opts.merge(processors:, prioritize: false))
 
         apply_all_processors_needing_type!
 
@@ -274,8 +275,25 @@ module Foobara
       end
 
       def value_caster
-        # TODO: how can declaration_data be blank? That seems really strange...
-        Value::Processor::Casting.new({ cast_to: declaration_data }, casters:, target_classes:)
+        # TODO: figure out what would be needed to successfully memoize this
+        # return @value_caster if defined?(@value_caster)
+
+        # We make this exception for :duck because it will match any instance of
+        # Object but AllowNil will match nil which is also an instance of Object.
+        # This results in two matching casters. Instead of figuring out a way to make one
+        # conditional on the other we will just turn off this unique enforcement for :duck
+        enforce_unique = if declaration_data.is_a?(::Hash)
+                           declaration_data[:type] != :duck
+                         else
+                           true
+                         end
+
+        Value::Processor::Casting.new(
+          { cast_to: declaration_data },
+          casters:,
+          target_classes:,
+          enforce_unique:
+        )
       end
 
       def applicable?(value)

data/projects/value/src/processor/casting.rb

@@ -39,7 +39,7 @@ module Foobara
 
         attr_accessor :target_classes
 
-        def initialize(*, casters:, target_classes: nil)
+        def initialize(*, casters:, target_classes: nil, **)
           self.target_classes = Util.array(target_classes)
 
           processors = [
@@ -47,7 +47,7 @@ module Foobara
             *casters
           ]
 
-          super(*, processors:)
+          super(*, processors:, **)
         end
 
         def needs_cast?(value)
@@ -113,7 +113,7 @@ module Foobara
             build_error(*args)
           elsif error_class == MoreThanOneApplicableProcessorError
             # :nocov:
-            raise "Matched too many casters for #{args.inspect} with #{opts.inspect}"
+            raise "Matched too many casters for #{args.map(&:inspect).join(",")} with #{opts.inspect}"
             # :nocov:
           else
             super

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: foobara
 version: !ruby/object:Gem::Version
-  version: 0.0.125
+  version: 0.0.127
 platform: ruby
 authors:
 - Miles Georgi
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -116,6 +116,7 @@ files:
 - projects/builtin_types/src/duck/supported_casters/allow_nil.rb
 - projects/builtin_types/src/duck/supported_validators/instance_of.rb
 - projects/builtin_types/src/duck/supported_validators/instance_of/type_declaration_extension/extend_registered_type_declaration/desugarizers/class_desugarizer.rb
+- projects/builtin_types/src/duck/supported_validators/instance_of/type_declaration_extension/extend_registered_type_declaration/desugarizers/class_type_desugarizer.rb
 - projects/builtin_types/src/duck/supported_validators/instance_of/type_declaration_extension/extend_registered_type_declaration/desugarizers/instance_of_class_desugarizer.rb
 - projects/builtin_types/src/duck/supported_validators/instance_of/type_declaration_extension/extend_registered_type_declaration/desugarizers/instance_of_symbol_desugarizer.rb
 - projects/builtin_types/src/duck/supported_validators/instance_of/type_declaration_extension/extend_registered_type_declaration/type_declaration_validators/is_valid_class.rb
@@ -528,7 +529,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A command-centric and discoverable software framework with a focus on domain
   concepts and abstracting away integration code