shared_tools 0.3.1 → 0.4.1

data/lib/shared_tools/tools/notification/linux_driver.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module SharedTools
+  module Tools
+    module Notification
+      # Linux notification driver.
+      #
+      # notify  — uses notify-send (libnotify); logs a warning if no display is available.
+      # alert   — uses zenity when a display is present; falls back to a terminal prompt.
+      # speak   — tries espeak-ng first, then espeak.
+      class LinuxDriver < BaseDriver
+        # @param message [String]
+        # @param title [String, nil]
+        # @param subtitle [String, nil] appended to the message body
+        # @param sound [String, nil] ignored on Linux
+        # @return [Hash]
+        def notify(message:, title: nil, subtitle: nil, sound: nil)
+          unless display_available?
+            RubyLLM.logger.warn('NotificationTool: No display server available, cannot show notification')
+            return { success: false, error: 'No display server available' }
+          end
+
+          unless command_available?('notify-send')
+            return { success: false, error: 'notify-send not found. Install libnotify-bin (Debian/Ubuntu) or libnotify (Fedora/Arch).' }
+          end
+
+          body = [message, subtitle].compact.join("\n")
+          cmd  = ['notify-send', (title || 'Notification'), body]
+          _, stderr, status = Open3.capture3(*cmd)
+          status.success? ? { success: true, action: 'notify' } : { success: false, error: stderr.strip }
+        end
+
+        # @param message [String]
+        # @param title [String, nil]
+        # @param buttons [Array<String>]
+        # @param default_button [String, nil]
+        # @return [Hash] includes :button with the label of the clicked button
+        def alert(message:, title: nil, buttons: ['OK'], default_button: nil)
+          if display_available? && command_available?('zenity')
+            alert_zenity(message:, title:, buttons:, default_button:)
+          else
+            alert_terminal(message:, buttons:, default_button:)
+          end
+        end
+
+        # @param text [String]
+        # @param voice [String, nil] espeak voice name (e.g. 'en', 'en-us')
+        # @param rate [Integer, nil] words per minute (espeak -s flag)
+        # @return [Hash]
+        def speak(text:, voice: nil, rate: nil)
+          binary = espeak_binary
+          unless binary
+            return { success: false, error: 'espeak-ng or espeak not found. Install espeak-ng (recommended) or espeak.' }
+          end
+
+          cmd  = [binary, text]
+          cmd += ['-v', voice]    if voice
+          cmd += ['-s', rate.to_s] if rate
+          _, stderr, status = Open3.capture3(*cmd)
+          status.success? ? { success: true, action: 'speak' } : { success: false, error: stderr.strip }
+        end
+
+        private
+
+        def display_available?
+          ENV['DISPLAY'] || ENV['WAYLAND_DISPLAY']
+        end
+
+        def espeak_binary
+          return 'espeak-ng' if command_available?('espeak-ng')
+          return 'espeak'    if command_available?('espeak')
+          nil
+        end
+
+        def alert_zenity(message:, title:, buttons:, default_button:)
+          if buttons.length == 1
+            cmd  = ['zenity', '--info', '--text', message]
+            cmd += ['--title', title] if title
+            _, stderr, status = Open3.capture3(*cmd)
+            status.success? ? { success: true, button: buttons.first } : { success: false, error: stderr.strip }
+          else
+            ok_label     = buttons[0]
+            cancel_label = buttons[1]
+            cmd  = ['zenity', '--question', '--text', message,
+                    '--ok-label', ok_label, '--cancel-label', cancel_label]
+            cmd += ['--title', title] if title
+            # zenity supports --extra-button for additional buttons beyond two
+            buttons[2..].each { |b| cmd += ['--extra-button', b] } if buttons.length > 2
+
+            stdout, stderr, status = Open3.capture3(*cmd)
+            case status.exitstatus
+            when 0 then { success: true, button: ok_label }
+            when 1 then { success: true, button: cancel_label }
+            else
+              btn = stdout.strip
+              btn.empty? ? { success: false, error: stderr.strip } : { success: true, button: btn }
+            end
+          end
+        end
+
+        def alert_terminal(message:, buttons:, default_button:)
+          $stdout.puts "\n[ALERT] #{message}"
+          $stdout.puts "Options: #{buttons.each_with_index.map { |b, i| "#{i + 1}) #{b}" }.join('  ')}"
+          $stdout.print "Enter choice (1-#{buttons.length}): "
+          $stdout.flush
+          input  = $stdin.gets&.strip.to_i
+          button = buttons[input - 1] || default_button || buttons.first
+          { success: true, button: button }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/notification/mac_driver.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module SharedTools
+  module Tools
+    module Notification
+      # macOS notification driver using osascript and the say command.
+      class MacDriver < BaseDriver
+        # @param message [String]
+        # @param title [String, nil]
+        # @param subtitle [String, nil]
+        # @param sound [String, nil] e.g. 'Glass', 'Ping'
+        # @return [Hash]
+        def notify(message:, title: nil, subtitle: nil, sound: nil)
+          parts = ["display notification #{message.inspect}"]
+          parts << "with title #{title.inspect}" if title
+          parts << "subtitle #{subtitle.inspect}"  if subtitle
+          parts << "sound name #{sound.inspect}"   if sound
+          run_osascript(parts.join(' '))
+            .then { |r| r[:success] ? r.merge(action: 'notify') : r }
+        end
+
+        # @param message [String]
+        # @param title [String, nil]
+        # @param buttons [Array<String>]
+        # @param default_button [String, nil]
+        # @return [Hash] includes :button with label of clicked button
+        def alert(message:, title: nil, buttons: ['OK'], default_button: nil)
+          btn_list  = buttons.map(&:inspect).join(', ')
+          script    = "display dialog #{message.inspect}"
+          script   += " with title #{title.inspect}" if title
+          script   += " buttons {#{btn_list}}"
+          script   += " default button #{default_button.inspect}" if default_button
+
+          stdout, stderr, status = Open3.capture3('osascript', '-e', script)
+          if status.success?
+            button = stdout.match(/button returned:(.+)/i)&.captures&.first&.strip
+            { success: true, button: button }
+          else
+            { success: false, error: stderr.strip }
+          end
+        end
+
+        # @param text [String]
+        # @param voice [String, nil] e.g. 'Samantha'
+        # @param rate [Integer, nil] words per minute
+        # @return [Hash]
+        def speak(text:, voice: nil, rate: nil)
+          cmd  = ['say', text]
+          cmd += ['-v', voice]    if voice
+          cmd += ['-r', rate.to_s] if rate
+          _, stderr, status = Open3.capture3(*cmd)
+          status.success? ? { success: true, action: 'speak' } : { success: false, error: stderr.strip }
+        end
+
+        private
+
+        def run_osascript(script)
+          _, stderr, status = Open3.capture3('osascript', '-e', script)
+          status.success? ? { success: true } : { success: false, error: stderr.strip }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/notification/null_driver.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    module Notification
+      # Fallback driver for unsupported platforms.
+      # All actions return a failure response with a clear error message.
+      class NullDriver < BaseDriver
+        def notify(message:, title: nil, subtitle: nil, sound: nil)
+          unsupported
+        end
+
+        def alert(message:, title: nil, buttons: ['OK'], default_button: nil)
+          unsupported
+        end
+
+        def speak(text:, voice: nil, rate: nil)
+          unsupported
+        end
+
+        private
+
+        def unsupported
+          { success: false, error: "NotificationTool is not supported on platform: #{RUBY_PLATFORM}" }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/notification.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Collection loader for notification tools
+# Usage: require 'shared_tools/tools/notification'
+
+require 'shared_tools'
+
+require_relative 'notification/base_driver'
+require_relative 'notification/mac_driver'
+require_relative 'notification/linux_driver'
+require_relative 'notification/null_driver'
+require_relative 'notification_tool'

data/lib/shared_tools/tools/notification_tool.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SharedTools
+  module Tools
+    # Cross-platform notification tool for desktop banners, modal dialogs, and TTS.
+    #
+    # Supports macOS (osascript, say) and Linux (notify-send, zenity/terminal, espeak-ng/espeak).
+    # On unsupported platforms all actions return {success: false}.
+    #
+    # @example Desktop notification
+    #   tool = SharedTools::Tools::NotificationTool.new
+    #   tool.execute(action: 'notify', message: 'Build complete', title: 'CI')
+    #
+    # @example Modal alert
+    #   result = tool.execute(action: 'alert', message: 'Deploy to production?', buttons: ['Yes', 'No'])
+    #   result[:button] # => 'Yes' or 'No'
+    #
+    # @example Text-to-speech
+    #   tool.execute(action: 'speak', message: 'Task finished')
+    class NotificationTool < ::RubyLLM::Tool
+      def self.name = 'notification_tool'
+
+      description <<~DESC.strip
+        Send desktop notifications, modal alerts, or text-to-speech messages.
+        Supports macOS and Linux. On macOS uses osascript and say.
+        On Linux uses notify-send, zenity (or terminal fallback), and espeak-ng/espeak.
+      DESC
+
+      params do
+        string :action, description: <<~TEXT.strip
+          The notification action to perform:
+          * `notify` — Non-blocking desktop banner notification.
+          * `alert`  — Modal dialog; waits for the user to click a button. Returns the button label.
+          * `speak`  — Speak text aloud using text-to-speech.
+        TEXT
+
+        string :message, description: "The message to display or speak. Required for all actions."
+
+        string :title, description: "Title for the notification or alert dialog. Optional.", required: false
+
+        string :subtitle, description: "Subtitle line (notify action, macOS and Linux). Optional.", required: false
+
+        string :sound, description: "Sound name to play with a notification (macOS only, e.g. 'Glass', 'Ping'). Optional.", required: false
+
+        array :buttons, of: :string, description: <<~TEXT.strip, required: false
+          Button labels for the alert dialog (e.g. ['Yes', 'No']). Defaults to ['OK'].
+        TEXT
+
+        string :default_button, description: "Default focused button label for the alert dialog. Optional.", required: false
+
+        string :voice, description: "TTS voice name for the speak action (e.g. 'Samantha' on macOS, 'en' on Linux). Optional.", required: false
+
+        integer :rate, description: "Speech rate in words per minute for the speak action. Optional.", required: false
+      end
+
+      # @param driver [Notification::BaseDriver] optional; auto-detected from platform if omitted
+      def initialize(driver: nil)
+        @driver = driver || default_driver
+      end
+
+      def execute(action:, message: nil, title: nil, subtitle: nil, sound: nil,
+                  buttons: nil, default_button: nil, voice: nil, rate: nil)
+        buttons ||= ['OK']
+
+        case action
+        when 'notify'
+          return missing_param('message', 'notify') if blank?(message)
+          @driver.notify(message:, title:, subtitle:, sound:)
+        when 'alert'
+          return missing_param('message', 'alert') if blank?(message)
+          @driver.alert(message:, title:, buttons:, default_button:)
+        when 'speak'
+          return missing_param('message', 'speak') if blank?(message)
+          @driver.speak(text: message, voice:, rate:)
+        else
+          { success: false, error: "Unknown action: #{action.inspect}. Must be notify, alert, or speak." }
+        end
+      end
+
+      private
+
+      def default_driver
+        case RUBY_PLATFORM
+        when /darwin/ then Notification::MacDriver.new
+        when /linux/  then Notification::LinuxDriver.new
+        else               Notification::NullDriver.new
+        end
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      def missing_param(param, action)
+        { success: false, error: "'#{param}' is required for the #{action} action" }
+      end
+    end
+  end
+end