shared_tools 0.3.1 → 0.4.1

data/lib/shared_tools/utilities.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+#
+# lib/shared_tools/utilities.rb
+#
+# General-purpose utility methods for SharedTools MCP clients and tools.
+# Loaded automatically by lib/shared_tools.rb.
+
+module SharedTools
+  MCP_LOG_MUTEX = Mutex.new
+  @mcp_load_log = {}
+
+  class << self
+
+    # ---------------------------------------------------------------------------
+    # MCP load tracking
+    # ---------------------------------------------------------------------------
+
+    # Record the outcome of loading a single MCP client.
+    # Called by mcp.rb from within each loader thread.
+    #
+    #   SharedTools.record_mcp_result("tavily")              # success
+    #   SharedTools.record_mcp_result("notion", error: e)    # failure
+    def record_mcp_result(name, error: nil)
+      MCP_LOG_MUTEX.synchronize do
+        @mcp_load_log[name] = error ? { status: :failed, reason: error.message } : { status: :ok }
+      end
+    end
+
+    # Returns an array of client names that loaded successfully.
+    #
+    #   SharedTools.mcp_loaded  #=> ["github", "memory", "chart"]
+    def mcp_loaded
+      MCP_LOG_MUTEX.synchronize { @mcp_load_log.select { |_, v| v[:status] == :ok }.keys }
+    end
+
+    # Returns a hash of client names that failed to load, mapped to their error messages.
+    #
+    #   SharedTools.mcp_failed  #=> {"tavily" => "Missing envars: TAVILY_API_KEY", ...}
+    def mcp_failed
+      MCP_LOG_MUTEX.synchronize do
+        @mcp_load_log.select { |_, v| v[:status] == :failed }.transform_values { |v| v[:reason] }
+      end
+    end
+
+    # Prints a summary table of MCP client load results and returns the full log hash.
+    #
+    #   SharedTools.mcp_status
+    #   # MCP Client Status
+    #   # ✓ github
+    #   # ✓ memory
+    #   # ✗ tavily   — Missing envars: TAVILY_API_KEY
+    def mcp_status
+      log = MCP_LOG_MUTEX.synchronize { @mcp_load_log.dup }
+
+      if log.empty?
+        puts "No MCP clients have been loaded yet. Try: require 'shared_tools/mcp'"
+        return log
+      end
+
+      puts "MCP Client Status"
+      puts "-" * 40
+      log.sort.each do |name, entry|
+        if entry[:status] == :ok
+          puts "  \u2713 #{name}"
+        else
+          puts "  \u2717 #{name}  \u2014 #{entry[:reason]}"
+        end
+      end
+      puts "-" * 40
+      puts "  #{log.count { |_, v| v[:status] == :ok }} loaded, " \
+           "#{log.count { |_, v| v[:status] == :failed }} skipped"
+
+      log
+    end
+
+    # Returns true if all named environment variables are set and non-empty.
+    # Warns for each missing variable and returns false if any are absent.
+    #
+    #   SharedTools.verify_envars("GITHUB_PERSONAL_ACCESS_TOKEN")
+    #   SharedTools.verify_envars("TAVILY_API_KEY", "ANOTHER_KEY")
+    def verify_envars(*names)
+      missing = names.select { |n| ENV.fetch(n, "").empty? }
+      missing.each { |n| warn "SharedTools — #{n} is not set" }
+      unless missing.empty?
+        raise LoadError, "Missing envars: #{missing.join(', ')}"
+      end
+    end
+
+    # High-level package installer. Detects the current platform and calls the
+    # appropriate *_install method. Raises LoadError if any package cannot be installed.
+    #
+    #   SharedTools.package_install("github-mcp-server")
+    #   SharedTools.package_install("curl", "jq")
+    def package_install(*packages)
+      case RUBY_PLATFORM
+      when /darwin/
+        brew_install(*packages)
+      when /linux/
+        if system("which apt-get > /dev/null 2>&1")
+          apt_install(*packages)
+        elsif system("which dnf > /dev/null 2>&1")
+          dnf_install(*packages)
+        elsif system("which brew > /dev/null 2>&1")
+          brew_install(*packages)
+        else
+          raise LoadError, "No supported package manager found (apt-get, dnf, brew)"
+        end
+      else
+        raise LoadError, "Unsupported platform: #{RUBY_PLATFORM}"
+      end
+    end
+
+    # Ensures each named binary is available in PATH, installing via brew if missing.
+    # Raises LoadError if brew is not installed or any package install fails.
+    #
+    #   SharedTools.brew_install("github-mcp-server")
+    #   SharedTools.brew_install("gh", "jq")
+    def brew_install(*packages)
+      raise LoadError, "Homebrew is not installed (https://brew.sh)" unless system("which brew > /dev/null 2>&1")
+
+      packages.each do |pkg|
+        next unless `brew list --versions #{pkg} 2>/dev/null`.strip.empty?
+
+        warn "SharedTools — #{pkg} not found, installing via brew..."
+        raise LoadError, "#{pkg} could not be installed" unless system("brew install --quiet #{pkg} > /dev/null 2>&1")
+      end
+    end
+
+    # Ensures each named binary is available in PATH, installing via apt-get if missing.
+    # Raises LoadError if any package install fails.
+    #
+    #   SharedTools.apt_install("curl")
+    #   SharedTools.apt_install("curl", "jq")
+    def apt_install(*packages)
+      packages.each do |pkg|
+        # SMELL: what if package is a library?
+        next if system("which #{pkg} > /dev/null 2>&1")
+
+        warn "SharedTools — #{pkg} not found, installing via apt-get..."
+        raise LoadError, "#{pkg} could not be installed" unless system("sudo apt-get install -y -q #{pkg} > /dev/null 2>&1")
+      end
+    end
+
+    # Ensures each named binary is available in PATH, installing via dnf if missing.
+    # Raises LoadError if any package install fails.
+    #
+    #   SharedTools.dnf_install("curl")
+    #   SharedTools.dnf_install("curl", "jq")
+    def dnf_install(*packages)
+      packages.each do |pkg|
+        # SMELL: What if package is a library?
+        next if system("which #{pkg} > /dev/null 2>&1")
+
+        warn "SharedTools — #{pkg} not found, installing via dnf..."
+        raise LoadError, "#{pkg} could not be installed" unless system("sudo dnf install -y -q #{pkg} > /dev/null 2>&1")
+      end
+    end
+
+    # Ensures each named npm package binary is available in PATH, installing
+    # globally via npm if missing. Raises LoadError if npm is not found or any install fails.
+    #
+    #   SharedTools.npm_install("typescript")
+    #   SharedTools.npm_install("typescript", "ts-node")
+    def npm_install(*packages)
+      raise LoadError, "npm is not installed (https://nodejs.org)" unless system("which npm > /dev/null 2>&1")
+
+      packages.each do |pkg|
+        # SMELL: What if package is a library?
+        next if system("which #{pkg} > /dev/null 2>&1")
+
+        warn "SharedTools — #{pkg} not found, installing via npm..."
+        raise LoadError, "#{pkg} could not be installed" unless system("npm install -g --silent #{pkg} > /dev/null 2>&1")
+      end
+    end
+
+    # Ensures each named gem is available, installing via gem install if missing.
+    # Raises LoadError if gem is not available or any install fails.
+    #
+    #   SharedTools.gem_install("nokogiri")
+    #   SharedTools.gem_install("nokogiri", "oj")
+    def gem_install(*packages)
+      raise LoadError, "gem is not available" unless system("which gem > /dev/null 2>&1")
+
+      packages.each do |pkg|
+        next if system("gem list -i #{pkg} > /dev/null 2>&1")
+
+        warn "SharedTools — #{pkg} not found, installing via gem..."
+        raise LoadError, "#{pkg} could not be installed" unless system("gem install --silent #{pkg} > /dev/null 2>&1")
+      end
+    end
+
+  end
+end

data/lib/shared_tools/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SharedTools
-  VERSION = "0.3.1"
+  VERSION = "0.4.1"
 end

data/lib/shared_tools/weather_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/weather_tool'
+require 'shared_tools'
+require 'shared_tools/tools/weather_tool'

data/lib/shared_tools/workflow_manager_tool.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+# Shim: require 'shared_tools/workflow_manager_tool'
+require 'shared_tools'
+require 'shared_tools/tools/workflow_manager_tool'

data/lib/shared_tools.rb

@@ -17,54 +17,27 @@ SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/disk.rb")
 SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/doc.rb")
 SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/docker.rb")
 SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/eval.rb")
+SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/notification.rb")
 SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/version.rb")  # Defines VERSION constant, not Version class
 SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/incomplete")  # Empty/incomplete tools directory
+SharedToolsLoader.ignore("#{__dir__}/shared_tools/tools/enabler.rb") # Experimental; defines Tools::Enabler not SharedTools::Tools::Enabler
+
+# Ignore per-tool shim files (require-path shortcuts: require 'shared_tools/<tool_name>')
+Dir.glob("#{__dir__}/shared_tools/*_tool.rb").each { |f| SharedToolsLoader.ignore(f) }
+SharedToolsLoader.ignore("#{__dir__}/shared_tools/data_science_kit.rb")
+SharedToolsLoader.ignore("#{__dir__}/shared_tools/database.rb")
+SharedToolsLoader.ignore("#{__dir__}/shared_tools/utilities.rb")  # Reopens SharedTools, not SharedTools::Utilities
+
 SharedToolsLoader.setup
 
 module SharedTools
-  @auto_execute ||= true # Auto-execute by default, no human-in-the-loop
-
+  @auto_execute   ||= true # Auto-execute by default, no human-in-the-loop
   class << self
+
     def auto_execute(wildwest=true)
       @auto_execute = wildwest
     end
 
-    # Load all tool classes so they're available via ObjectSpace
-    # Call this when using AIA with --rq shared_tools
-    # Uses manual loading to gracefully handle missing dependencies
-    def load_all_tools
-      tools_dir = File.join(__dir__, 'shared_tools', 'tools')
-      Dir.glob(File.join(tools_dir, '*_tool.rb')).each do |tool_file|
-        begin
-          require tool_file
-        rescue LoadError => e
-          # Skip tools with missing dependencies
-          warn "SharedTools: Skipping #{File.basename(tool_file)} - #{e.message}" if ENV['DEBUG']
-        end
-      end
-    end
-
-    # Get all available tool classes (those that inherit from RubyLLM::Tool)
-    # Only returns tools that can be successfully instantiated without arguments (RubyLLM requirement)
-    def tools
-      load_all_tools
-      ObjectSpace.each_object(Class).select do |klass|
-        next false unless klass < RubyLLM::Tool
-        next false unless klass.to_s.start_with?('SharedTools::')
-
-        # Actually try to instantiate the tool to verify it works
-        # RubyLLM calls tool.new without args, so tools must be instantiable this way
-        begin
-          klass.new
-          true
-        rescue ArgumentError, LoadError, StandardError => e
-          # Skip tools that can't be instantiated (missing args, missing platform drivers, etc.)
-          warn "SharedTools: Excluding #{klass} - #{e.message}" if ENV['DEBUG']
-          false
-        end
-      end
-    end
-
     def execute?(tool: 'unknown', stuff: '')
       # Return true if auto_execute is explicitly enabled
       return true if @auto_execute == true
@@ -78,5 +51,22 @@ module SharedTools
       print "\nIs it okay to proceed? (y/N"
       STDIN.getch == "y"
     end
+
+    # Force-load all tool classes into ObjectSpace.
+    # Called by AIA's GemActivator.trigger_tool_loading when shared_tools is
+    # passed to --require. Without this, Zeitwerk lazy-loads classes on first
+    # reference, so no RubyLLM::Tool subclasses appear in ObjectSpace at scan time.
+    def load_all_tools
+      SharedToolsLoader.eager_load
+    end
+
+    # Return all loaded RubyLLM::Tool subclasses provided by this gem.
+    # Also triggers eager loading so the list is complete.
+    def tools
+      load_all_tools
+      ObjectSpace.each_object(Class).select { |k| k < ::RubyLLM::Tool }.to_a
+    end
   end
 end
+
+require_relative "shared_tools/utilities"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shared_tools
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -122,7 +122,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: docx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: roo
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -136,7 +150,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: watir
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -150,7 +164,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: webdrivers
+  name: ferrum
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -219,6 +233,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -246,10 +274,34 @@ files:
 - LICENSE
 - README.md
 - lib/shared_tools.rb
+- lib/shared_tools/browser_tool.rb
+- lib/shared_tools/calculator_tool.rb
+- lib/shared_tools/clipboard_tool.rb
+- lib/shared_tools/composite_analysis_tool.rb
+- lib/shared_tools/computer_tool.rb
+- lib/shared_tools/cron_tool.rb
+- lib/shared_tools/current_date_time_tool.rb
+- lib/shared_tools/data_science_kit.rb
+- lib/shared_tools/database.rb
+- lib/shared_tools/database_query_tool.rb
+- lib/shared_tools/database_tool.rb
+- lib/shared_tools/disk_tool.rb
+- lib/shared_tools/dns_tool.rb
+- lib/shared_tools/doc_tool.rb
+- lib/shared_tools/error_handling_tool.rb
+- lib/shared_tools/eval_tool.rb
 - lib/shared_tools/mcp.rb
-- lib/shared_tools/mcp/github_mcp_server.rb
-- lib/shared_tools/mcp/imcp.rb
-- lib/shared_tools/mcp/tavily_mcp_server.rb
+- lib/shared_tools/mcp/brave_search_client.rb
+- lib/shared_tools/mcp/chart_client.rb
+- lib/shared_tools/mcp/github_client.rb
+- lib/shared_tools/mcp/hugging_face_client.rb
+- lib/shared_tools/mcp/memory_client.rb
+- lib/shared_tools/mcp/notion_client.rb
+- lib/shared_tools/mcp/sequential_thinking_client.rb
+- lib/shared_tools/mcp/slack_client.rb
+- lib/shared_tools/mcp/streamable_http_patch.rb
+- lib/shared_tools/mcp/tavily_client.rb
+- lib/shared_tools/system_info_tool.rb
 - lib/shared_tools/tools.rb
 - lib/shared_tools/tools/browser.rb
 - lib/shared_tools/tools/browser/base_driver.rb
@@ -257,6 +309,7 @@ files:
 - lib/shared_tools/tools/browser/click_tool.rb
 - lib/shared_tools/tools/browser/elements/element_grouper.rb
 - lib/shared_tools/tools/browser/elements/nearby_element_detector.rb
+- lib/shared_tools/tools/browser/ferrum_driver.rb
 - lib/shared_tools/tools/browser/formatters/action_formatter.rb
 - lib/shared_tools/tools/browser/formatters/data_entry_formatter.rb
 - lib/shared_tools/tools/browser/formatters/element_formatter.rb
@@ -293,7 +346,6 @@ files:
 - lib/shared_tools/tools/database/sqlite_driver.rb
 - lib/shared_tools/tools/database_query_tool.rb
 - lib/shared_tools/tools/database_tool.rb
-- lib/shared_tools/tools/devops_toolkit.rb
 - lib/shared_tools/tools/disk.rb
 - lib/shared_tools/tools/disk/base_driver.rb
 - lib/shared_tools/tools/disk/base_tool.rb
@@ -311,23 +363,36 @@ files:
 - lib/shared_tools/tools/disk_tool.rb
 - lib/shared_tools/tools/dns_tool.rb
 - lib/shared_tools/tools/doc.rb
+- lib/shared_tools/tools/doc/docx_reader_tool.rb
 - lib/shared_tools/tools/doc/pdf_reader_tool.rb
+- lib/shared_tools/tools/doc/spreadsheet_reader_tool.rb
+- lib/shared_tools/tools/doc/text_reader_tool.rb
 - lib/shared_tools/tools/doc_tool.rb
 - lib/shared_tools/tools/docker.rb
 - lib/shared_tools/tools/docker/base_tool.rb
 - lib/shared_tools/tools/docker/compose_run_tool.rb
+- lib/shared_tools/tools/enabler.rb
 - lib/shared_tools/tools/error_handling_tool.rb
 - lib/shared_tools/tools/eval.rb
 - lib/shared_tools/tools/eval/python_eval_tool.rb
 - lib/shared_tools/tools/eval/ruby_eval_tool.rb
 - lib/shared_tools/tools/eval/shell_eval_tool.rb
 - lib/shared_tools/tools/eval_tool.rb
+- lib/shared_tools/tools/notification.rb
+- lib/shared_tools/tools/notification/base_driver.rb
+- lib/shared_tools/tools/notification/linux_driver.rb
+- lib/shared_tools/tools/notification/mac_driver.rb
+- lib/shared_tools/tools/notification/null_driver.rb
+- lib/shared_tools/tools/notification_tool.rb
 - lib/shared_tools/tools/secure_tool_template.rb
 - lib/shared_tools/tools/system_info_tool.rb
 - lib/shared_tools/tools/version.rb
 - lib/shared_tools/tools/weather_tool.rb
 - lib/shared_tools/tools/workflow_manager_tool.rb
+- lib/shared_tools/utilities.rb
 - lib/shared_tools/version.rb
+- lib/shared_tools/weather_tool.rb
+- lib/shared_tools/workflow_manager_tool.rb
 homepage: https://github.com/madbomber/shared_tools
 licenses:
 - MIT
@@ -349,7 +414,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Shared utilities and AI tools for Ruby applications with configurable logging
 test_files: []

data/lib/shared_tools/mcp/github_mcp_server.rb

@@ -1,58 +0,0 @@
-# shared_tools/mcp/github_mcp_server.rb
-#
-# GitHub MCP Server Client Configuration for ruby_llm-mcp >= 0.7.0
-#
-# Provides access to GitHub operations including:
-#   - Repository management
-#   - Issue and PR operations
-#   - Code search
-#   - Branch operations
-#   - And more GitHub API functionality
-#
-# Installation:
-#   brew install github-mcp-server
-#
-# Configuration:
-#   Set environment variable: GITHUB_PERSONAL_ACCESS_TOKEN
-#   export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
-#
-# Compatible with ruby_llm-mcp v0.7.0+
-
-require "ruby_llm/mcp"
-
-RubyLLM::MCP.add_client(
-  name: "github-mcp-server",
-  transport_type: :stdio,
-  config: {
-    command: "/opt/homebrew/bin/github-mcp-server",
-    args: %w[stdio],
-    env: { "GITHUB_PERSONAL_ACCESS_TOKEN" => ENV.fetch("GITHUB_PERSONAL_ACCESS_TOKEN") },
-  },
-)
-
-
-__END__
-
-
-A GitHub MCP server that handles various tools and resources.
-
-Usage:
-  server [command]
-
-Available Commands:
-  completion  Generate the autocompletion script for the specified shell
-  help        Help about any command
-  stdio       Start stdio server
-
-Flags:
-      --dynamic-toolsets         Enable dynamic toolsets
-      --enable-command-logging   When enabled, the server will log all command requests and responses to the log file
-      --export-translations      Save translations to a JSON file
-      --gh-host string           Specify the GitHub hostname (for GitHub Enterprise etc.)
-  -h, --help                     help for server
-      --log-file string          Path to log file
-      --read-only                Restrict the server to read-only operations
-      --toolsets strings         An optional comma separated list of groups of tools to allow, defaults to enabling all (default [all])
-  -v, --version                  version for server
-
-Use "server [command] --help" for more information about a command.

data/lib/shared_tools/mcp/imcp.rb

@@ -1,28 +0,0 @@
-# shared_tools/mcp/imcp.rb
-#
-# iMCP Client Configuration for ruby_llm-mcp >= 0.7.0
-#
-# iMCP is a macOS application that provides MCP access to:
-#   - Notes
-#   - Calendar
-#   - Contacts
-#   - Reminders
-#   - And other macOS native applications
-#
-# Installation:
-#   brew install --cask loopwork/tap/iMCP
-#
-# Documentation:
-#   https://github.com/loopwork/iMCP
-#
-# Compatible with ruby_llm-mcp v0.7.0+
-
-require 'ruby_llm/mcp'
-
-RubyLLM::MCP.add_client(
-  name: "imcp-server",
-  transport_type: :stdio,
-  config: {
-    command: "/Applications/iMCP.app/Contents/MacOS/imcp-server 2> /dev/null"
-  }
-)

data/lib/shared_tools/mcp/tavily_mcp_server.rb

@@ -1,44 +0,0 @@
-# shared_tools/mcp/tavily_mcp_server.rb
-#
-# Tavily MCP Server Client Configuration for ruby_llm-mcp >= 0.7.0
-#
-# Provides AI-powered web search and research capabilities:
-#   - Web search with AI-optimized results
-#   - Research-grade content extraction
-#   - Real-time information gathering
-#   - News and current events search
-#
-# Installation:
-#   Requires Node.js and npx (comes with Node.js)
-#   The mcp-remote package will be installed automatically via npx
-#
-# Configuration:
-#   Set environment variable: TAVILY_API_KEY
-#   export TAVILY_API_KEY=your_api_key_here
-#   Get your API key at: https://tavily.com
-#
-# Compatible with ruby_llm-mcp v0.7.0+
-
-require "ruby_llm/mcp"
-
-RubyLLM::MCP.add_client(
-  name: "tavily",
-  transport_type: :stdio,
-  config: {
-    command: "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=#{ENV.fetch('TAVILY_API_KEY')}",
-    env: {}
-  }
-)
-
-
-__END__
-
-
-# {
-#   "mcpServers": {
-#     "tavily-remote-mcp": {
-#       "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=$TAVILY_API_KEY",
-#       "env": {}
-#     }
-#   }
-# }