ruby-mana 0.5.1 → 0.5.7

data/lib/mana/mixin.rb

@@ -11,8 +11,8 @@ module Mana
     module ClassMethods
       # Mark a method for LLM compilation.
       # Usage:
-      #   mana def fizzbuzz(n)
-      #     ~"return FizzBuzz array from 1 to n"
+      #   mana def fibonacci(n)
+      #     ~"return an array of the first n Fibonacci numbers"
       #   end
       def mana(method_name)
         Mana::Compiler.compile(self, method_name)

data/lib/mana/mock.rb

@@ -1,23 +1,39 @@
 # frozen_string_literal: true
 
 module Mana
+  # Test double for LLM calls. Stubs are matched against prompt text:
+  #   Regexp patterns use match?, String patterns use include?.
+  #
+  # Usage:
+  #   Mana.mock do
+  #     prompt(/average/, result: 3.0)
+  #     ~"compute average of <numbers> and store in <result>"
+  #   end
+  #
+  # Thread-local — safe for parallel test execution.
   class Mock
     Stub = Struct.new(:pattern, :values, :block, keyword_init: true)
 
     attr_reader :stubs
 
+    # Initialize with an empty stub list
     def initialize
       @stubs = []
     end
 
+    # Register a stub: when a prompt matches `pattern`, return `values` or call `block`
     def prompt(pattern, **values, &block)
       @stubs << Stub.new(pattern: pattern, values: values, block: block)
     end
 
+    # Find the first stub that matches the given prompt text.
+    # Regexp patterns use match?, String patterns use include?.
     def match(prompt_text)
       @stubs.find do |stub|
         case stub.pattern
+        # Regex: full pattern match
         when Regexp then prompt_text.match?(stub.pattern)
+        # String: substring match
         when String then prompt_text.include?(stub.pattern)
         end
       end
@@ -25,29 +41,53 @@ module Mana
   end
 
   class << self
+    # Run a block with a mock active. Stubs defined inside are scoped to this block.
+    # The block is instance_eval'd on the Mock so `prompt` is available as DSL.
     def mock(&block)
       old_mock = Thread.current[:mana_mock]
       m = Mock.new
       Thread.current[:mana_mock] = m
       m.instance_eval(&block)
+    # Always restore the previous mock (supports nesting)
     ensure
       Thread.current[:mana_mock] = old_mock
     end
 
+    # Enable mock mode (for use with before/after hooks in tests)
     def mock!
       Thread.current[:mana_mock] = Mock.new
     end
 
+    # Disable mock mode and restore normal LLM calls
     def unmock!
       Thread.current[:mana_mock] = nil
     end
 
+    # Check if mock mode is currently active on this thread
     def mock_active?
       !Thread.current[:mana_mock].nil?
     end
 
+    # Returns the current thread's Mock instance, or nil if not in mock mode
     def current_mock
       Thread.current[:mana_mock]
     end
   end
+
+  # RSpec helper — include in your test suite for automatic mock setup.
+  #   RSpec.configure { |c| c.include Mana::TestHelpers }
+  module TestHelpers
+    # Auto-enable mock mode before each test, disable after
+    def self.included(base)
+      base.before { Mana.mock! }
+      base.after { Mana.unmock! }
+    end
+
+    # Convenience method to register a stub within the current mock context
+    def mock_prompt(pattern, **values, &block)
+      raise Mana::MockError, "Mana mock mode not active. Call Mana.mock! first" unless Mana.mock_active?
+
+      Mana.current_mock.prompt(pattern, **values, &block)
+    end
+  end
 end

data/lib/mana/security_policy.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Mana
+  # Configurable security policy for LLM tool calls.
+  #
+  # Five levels (higher = more permissions, each includes all below):
+  #   0 :sandbox    — variables and user functions only
+  #   1 :strict     — + safe stdlib (Time, Date, Math)
+  #   2 :standard   — + read filesystem (File.read, Dir.glob) [default]
+  #   3 :permissive — + write files, network, require
+  #   4 :danger     — no restrictions
+  #
+  # Usage:
+  #   Mana.configure { |c| c.security = :standard }
+  #   Mana.configure { |c| c.security = 2 }
+  #   Mana.configure do |c|
+  #     c.security = :strict
+  #     c.security.allow_receiver "File", only: %w[read exist?]
+  #   end
+  class SecurityPolicy
+    LEVELS = { sandbox: 0, strict: 1, standard: 2, permissive: 3, danger: 4 }.freeze
+
+    # Methods blocked at each level. Higher levels remove restrictions.
+    PRESETS = {
+      sandbox: {
+        blocked_methods: %w[
+          methods singleton_methods private_methods protected_methods public_methods
+          instance_variables instance_variable_get instance_variable_set remove_instance_variable
+          local_variables global_variables
+          send __send__ public_send eval instance_eval instance_exec class_eval module_eval
+          system exec fork spawn ` require require_relative load
+          exit exit! abort at_exit
+        ],
+        blocked_receivers: :all
+      },
+      strict: {
+        blocked_methods: %w[
+          methods singleton_methods private_methods protected_methods public_methods
+          instance_variables instance_variable_get instance_variable_set remove_instance_variable
+          local_variables global_variables
+          send __send__ public_send eval instance_eval instance_exec class_eval module_eval
+          system exec fork spawn ` require require_relative load
+          exit exit! abort at_exit
+        ],
+        blocked_receivers: {
+          "File" => :all, "Dir" => :all, "IO" => :all,
+          "Kernel" => :all, "Process" => :all, "ObjectSpace" => :all, "ENV" => :all
+        }
+      },
+      standard: {
+        blocked_methods: %w[
+          methods singleton_methods private_methods protected_methods public_methods
+          instance_variables instance_variable_get instance_variable_set remove_instance_variable
+          local_variables global_variables
+          send __send__ public_send eval instance_eval instance_exec class_eval module_eval
+          system exec fork spawn `
+          exit exit! abort at_exit
+          require require_relative load
+        ],
+        blocked_receivers: {
+          "File" => Set.new(%w[delete write open chmod chown rename unlink]),
+          "Dir" => Set.new(%w[delete rmdir mkdir chdir]),
+          "IO" => :all, "Kernel" => :all, "Process" => :all,
+          "ObjectSpace" => :all, "ENV" => :all
+        }
+      },
+      permissive: {
+        blocked_methods: %w[
+          eval instance_eval instance_exec class_eval module_eval
+          system exec fork spawn `
+          exit exit! abort at_exit
+        ],
+        blocked_receivers: {
+          "ObjectSpace" => :all
+        }
+      },
+      danger: {
+        blocked_methods: [],
+        blocked_receivers: {}
+      }
+    }.freeze
+
+    attr_reader :preset
+
+    # Initialize security policy from a preset name (Symbol) or numeric level (Integer)
+    def initialize(preset = :strict)
+      # Convert numeric level to its corresponding symbol name
+      preset = LEVELS.key(preset) if preset.is_a?(Integer)
+      raise ArgumentError, "unknown security level: #{preset.inspect}. Use: #{LEVELS.keys.join(', ')}" unless PRESETS.key?(preset)
+
+      @preset = preset
+      data = PRESETS[preset]
+      @blocked_methods = Set.new(data[:blocked_methods])
+
+      if data[:blocked_receivers] == :all
+        # Sandbox mode: block all receiver calls by default
+        @block_all_receivers = true
+        @blocked_receivers = {}
+      else
+        # Other modes: block only specific methods on specific receivers
+        @block_all_receivers = false
+        @blocked_receivers = data[:blocked_receivers].transform_values { |v|
+          v == :all ? :all : Set.new(v)
+        }
+      end
+
+      # Allowlist overrides added via allow_receiver(name, only: [...])
+      @allowed_overrides = {}
+      yield self if block_given?
+    end
+
+    # --- Mutators ---
+
+    def allow_method(name)
+      @blocked_methods.delete(name.to_s)
+    end
+
+    def block_method(name)
+      @blocked_methods.add(name.to_s)
+    end
+
+    # Allow a receiver's calls. With `only:`, allowlist specific methods;
+    # without it, fully unblock the receiver.
+    def allow_receiver(name, only: nil)
+      name = name.to_s
+      if only
+        # Allowlist only the specified methods (override takes priority over block rules)
+        @allowed_overrides[name] = Set.new(only.map(&:to_s))
+      else
+        # Fully unblock the receiver and remove any override
+        @blocked_receivers.delete(name)
+        @allowed_overrides.delete(name)
+      end
+    end
+
+    # Block a receiver's calls. With `only:`, block specific methods;
+    # without it, block all methods on the receiver.
+    def block_receiver(name, only: nil)
+      name = name.to_s
+      if only
+        existing = @blocked_receivers[name]
+        if existing == :all
+          # Already fully blocked — nothing to add
+        elsif existing.is_a?(Set)
+          # Merge new blocked methods into the existing set
+          existing.merge(only.map(&:to_s))
+        else
+          # First partial block rule for this receiver
+          @blocked_receivers[name] = Set.new(only.map(&:to_s))
+        end
+      else
+        # Block all methods on this receiver
+        @blocked_receivers[name] = :all
+        @allowed_overrides.delete(name)
+      end
+    end
+
+    # --- Queries ---
+
+    def method_blocked?(name)
+      @blocked_methods.include?(name.to_s)
+    end
+
+    # Check whether calling `method` on `receiver` is blocked by the policy
+    def receiver_call_blocked?(receiver, method)
+      # Danger mode has no restrictions at all
+      return false if @preset == :danger
+
+      r, m = receiver.to_s, method.to_s
+
+      # Sandbox mode: block everything unless explicitly allowlisted
+      if @block_all_receivers
+        return !(@allowed_overrides.key?(r) && @allowed_overrides[r].include?(m))
+      end
+
+      # Receiver not in the block list — allow
+      rule = @blocked_receivers[r]
+      return false if rule.nil?
+
+      # Allowlist override takes priority: if user explicitly allowed this method, pass
+      if @allowed_overrides.key?(r) && @allowed_overrides[r].include?(m)
+        return false
+      end
+
+      # Blocked if receiver is fully blocked (:all) or method is in the blocked set
+      rule == :all || rule.include?(m)
+    end
+
+    def level
+      LEVELS[@preset]
+    end
+  end
+end

data/lib/mana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mana
-  VERSION = "0.5.1"
+  VERSION = "0.5.7"
 end

data/lib/mana.rb

@@ -2,21 +2,13 @@
 
 require_relative "mana/version"
 require_relative "mana/config"
+require_relative "mana/security_policy"
 require_relative "mana/backends/base"
 require_relative "mana/backends/anthropic"
 require_relative "mana/backends/openai"
-require_relative "mana/backends/registry"
-require_relative "mana/effect_registry"
-require_relative "mana/namespace"
 require_relative "mana/memory_store"
-require_relative "mana/context_window"
 require_relative "mana/memory"
-require_relative "mana/object_registry"
-require_relative "mana/remote_ref"
-require_relative "mana/engines/base"
-require_relative "mana/engines/llm"
-require_relative "mana/engines/ruby_eval"
-require_relative "mana/engines/detect"
+require_relative "mana/logger"
 require_relative "mana/engine"
 require_relative "mana/introspect"
 require_relative "mana/compiler"
@@ -25,48 +17,33 @@ require_relative "mana/mixin"
 
 module Mana
   class Error < StandardError; end
+  class ConfigError < Error; end
   class MaxIterationsError < Error; end
   class LLMError < Error; end
   class MockError < Error; end
 
   class << self
+    # Return the global config singleton (lazy-initialized)
     def config
       @config ||= Config.new
     end
 
+    # Yield the config for modification, return the config instance
     def configure
       yield(config) if block_given?
       config
     end
 
+    # Shortcut to set the model name directly
     def model=(model)
       config.model = model
     end
 
-    def handle(handler = nil, **opts, &block)
-      Engine.with_handler(handler, **opts, &block)
-    end
-
+    # Reset all global state: config, thread-local memory and mock
     def reset!
       @config = Config.new
-      EffectRegistry.clear!
-      Engines.reset_detector!
-      ObjectRegistry.reset!
-      Engines::JavaScript.reset! if defined?(Engines::JavaScript)
-      Engines::Python.reset! if defined?(Engines::Python)
       Thread.current[:mana_memory] = nil
       Thread.current[:mana_mock] = nil
-      Thread.current[:mana_last_engine] = nil
-    end
-
-    # Define a custom effect that becomes an LLM tool
-    def define_effect(name, description: nil, &handler)
-      EffectRegistry.define(name, description: description, &handler)
-    end
-
-    # Remove a custom effect
-    def undefine_effect(name)
-      EffectRegistry.undefine(name)
     end
 
     # Access current thread's memory

metadata

@@ -1,43 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.7
 platform: ruby
 authors:
-- Carl
+- Carl Li
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: mini_racer
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.16'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.16'
 description: |
   Mana lets you write natural language strings in Ruby that execute via LLM
   with full access to your program's live state. Read/write variables, call
@@ -50,41 +36,29 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- data/lang-rules.yml
 - lib/mana.rb
 - lib/mana/backends/anthropic.rb
 - lib/mana/backends/base.rb
 - lib/mana/backends/openai.rb
-- lib/mana/backends/registry.rb
 - lib/mana/compiler.rb
 - lib/mana/config.rb
-- lib/mana/context_window.rb
-- lib/mana/effect_registry.rb
 - lib/mana/engine.rb
-- lib/mana/engines/base.rb
-- lib/mana/engines/detect.rb
-- lib/mana/engines/javascript.rb
-- lib/mana/engines/llm.rb
-- lib/mana/engines/python.rb
-- lib/mana/engines/ruby_eval.rb
 - lib/mana/introspect.rb
+- lib/mana/logger.rb
 - lib/mana/memory.rb
 - lib/mana/memory_store.rb
 - lib/mana/mixin.rb
 - lib/mana/mock.rb
-- lib/mana/namespace.rb
-- lib/mana/object_registry.rb
-- lib/mana/remote_ref.rb
+- lib/mana/security_policy.rb
 - lib/mana/string_ext.rb
-- lib/mana/test.rb
 - lib/mana/version.rb
-homepage: https://github.com/carlnoah6/ruby-mana
+homepage: https://github.com/twokidsCarl/ruby-mana
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/carlnoah6/ruby-mana
-  source_code_uri: https://github.com/carlnoah6/ruby-mana
-  changelog_uri: https://github.com/carlnoah6/ruby-mana/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/twokidsCarl/ruby-mana
+  source_code_uri: https://github.com/twokidsCarl/ruby-mana
+  changelog_uri: https://github.com/twokidsCarl/ruby-mana/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -93,7 +67,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.0
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/data/lang-rules.yml

@@ -1,196 +0,0 @@
-version: 1
-languages:
-  javascript:
-    strong:
-      - "const "
-      - "let "
-      - "=> "
-      - "=== "
-      - "!== "
-      - "console.log"
-      - "console.error"
-      - ".filter("
-      - ".map("
-      - ".reduce("
-      - ".forEach("
-      - ".indexOf("
-      - ".push("
-      - "function "
-      - "async "
-      - "await "
-      - "require("
-      - "module.exports"
-      - "export "
-      - "import "
-      - "new Promise"
-      - "document."
-      - "window."
-      - "JSON.parse"
-      - "JSON.stringify"
-      - "typeof "
-      - "undefined"
-      - "null;"
-    weak:
-      - "var "
-      - "return "
-      - "true"
-      - "false"
-      - "null"
-      - "this."
-    anti:
-      - "let me"
-      - "let us"
-      - "let's"
-      - "const ant"
-      - "import ant"
-      - "import this"
-    patterns:
-      - "\\bfunction\\s+\\w+\\s*\\("
-      - "\\(\\s*\\w+\\s*\\)\\s*=>"
-      - "\\bclass\\s+\\w+\\s*\\{"
-
-  python:
-    strong:
-      - "elif "
-      - "print("
-      - "__init__"
-      - "__name__"
-      - "self."
-      - "import numpy"
-      - "import pandas"
-      - "lambda "
-      - "except "
-      - "finally:"
-      - "nonlocal "
-    weak:
-      - "def "
-      - "from "
-      - "yield "
-      - "raise "
-      - "assert "
-      - "global "
-      - "import "
-      - "return "
-      - "class "
-      - "for "
-      - "while "
-      - "if "
-      - "is not"
-      - "not in"
-      - "pass "
-    anti:
-      - "import this"
-      - "import that"
-      - "from here"
-      - "from there"
-      - "for example"
-      - "for instance"
-      - "while I"
-      - "while we"
-      - "if you"
-      - "if we"
-      - "with you"
-      - "with the"
-      - "with a "
-      - "with my"
-      - "and the"
-      - "and I"
-      - "and we"
-      - "or the"
-      - "or a "
-      - "or I"
-      - "or False"
-      - "True or"
-      - "as a "
-      - "as the"
-      - "as I"
-      - "pass the"
-      - "pass it"
-      - "pass on"
-    patterns:
-      - "\\[.+\\bfor\\b.+\\bin\\b.+\\]"
-      - "\\bdef\\s+\\w+\\s*\\("
-      - "\\bclass\\s+\\w+\\s*[:(]"
-      - "^\\s{4}"
-
-  ruby:
-    strong:
-      - "puts "
-      - "require "
-      - "require_relative"
-      - "attr_accessor"
-      - "attr_reader"
-      - "attr_writer"
-      - ".each "
-      - ".map "
-      - ".select "
-      - ".reject "
-      - "do |"
-      - "def "
-      - "module "
-      - "rescue "
-      - "ensure "
-      - "unless "
-      - "until "
-      - "elsif "
-      - "nil"
-      - "p "
-      - "pp "
-      - "Proc.new"
-      - "lambda {"
-      - "-> {"
-    weak:
-      - "end "
-      - "begin "
-      - "class "
-      - "return "
-      - "if "
-      - "for "
-      - "while "
-    anti:
-      - "the end"
-      - "in the end"
-      - "at the end"
-      - "begin with"
-      - "begin to"
-    patterns:
-      - "\\bdo\\s*\\|\\w+\\|"
-      - "\\bdef\\s+\\w+[?!]?"
-      - "\\bend\\b"
-
-  natural_language:
-    strong:
-      - "please "
-      - "analyze "
-      - "summarize "
-      - "translate "
-      - "explain "
-      - "find "
-      - "calculate "
-      - "generate "
-      - "create "
-      - "write "
-      - "describe "
-      - "compare "
-      - "store in <"
-      - "save in <"
-      - "put in <"
-      - ", store "
-      - ", save "
-    weak:
-      - "the "
-      - "a "
-      - "an "
-      - "is "
-      - "are "
-      - "was "
-      - "were "
-      - "what "
-      - "how "
-      - "why "
-      - "when "
-      - "where "
-      - "which "
-    anti: []
-    patterns:
-      - "<\\w+>"