pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/channels/telegram.rb

@@ -4,9 +4,9 @@ require "telegram/bot"
 
 module Pocketrb
   module Channels
-    # Telegram channel using long polling
-    # Simple and reliable - no webhook/public IP needed
+    # Telegram channel using long polling. Simple and reliable - no webhook/public IP needed
     class Telegram < Base
+      # Markdown to HTML conversion patterns for Telegram formatting
       MARKDOWN_TO_HTML = {
         # Bold **text** or __text__
         /\*\*(.+?)\*\*/ => '<b>\1</b>',
@@ -19,6 +19,7 @@ module Pocketrb
         /`([^`]+)`/ => '<code>\1</code>'
       }.freeze
 
+      # Telegram file download URL template
       TELEGRAM_FILE_URL = "https://api.telegram.org/file/bot%<token>s/%<path>s"
 
       # Special commands that bypass the agent
@@ -26,6 +27,11 @@ module Pocketrb
 
       attr_accessor :status_context
 
+      # Initialize Telegram channel
+      # @param bus [Bus::MessageBus] Message bus for publishing and consuming messages
+      # @param token [String] Telegram bot API token
+      # @param allowed_users [Array<String, Integer>, nil] Allowed usernames or user IDs (nil = allow all)
+      # @param download_media [Boolean] Whether to download and process media attachments (defaults to true)
       def initialize(bus:, token:, allowed_users: nil, download_media: true)
         super(bus: bus, name: :telegram)
         @token = token
@@ -40,6 +46,7 @@ module Pocketrb
 
       protected
 
+      # Start the Telegram bot listener thread using long polling
       def run_inbound_loop
         Pocketrb.logger.info("Starting Telegram bot (polling mode)...")
 
@@ -73,6 +80,8 @@ module Pocketrb
         raise
       end
 
+      # Send an outbound message via the Telegram API, with HTML formatting
+      # @param message [Bus::OutboundMessage] outbound message to deliver
       def send_message(message)
         return unless @bot
 
@@ -107,6 +116,9 @@ module Pocketrb
         end
       end
 
+      # Dispatch a media item to the appropriate Telegram send method
+      # @param chat_id [Integer] Telegram chat identifier
+      # @param media [Media::Item] media attachment to send
       def send_media(chat_id, media)
         case media.type
         when :image
@@ -122,21 +134,33 @@ module Pocketrb
         Pocketrb.logger.error("Error sending media: #{e.message}")
       end
 
+      # Upload and send a photo via the Telegram API
+      # @param chat_id [Integer] Telegram chat identifier
+      # @param media [Media::Item] image media item
       def send_photo(chat_id, media)
         file = Faraday::Multipart::FilePart.new(media.path, media.mime_type, media.filename)
         @bot.api.send_photo(chat_id: chat_id, photo: file)
       end
 
+      # Upload and send an audio file via the Telegram API
+      # @param chat_id [Integer] Telegram chat identifier
+      # @param media [Media::Item] audio media item
       def send_audio(chat_id, media)
         file = Faraday::Multipart::FilePart.new(media.path, media.mime_type, media.filename)
         @bot.api.send_audio(chat_id: chat_id, audio: file)
       end
 
+      # Upload and send a video file via the Telegram API
+      # @param chat_id [Integer] Telegram chat identifier
+      # @param media [Media::Item] video media item
       def send_video(chat_id, media)
         file = Faraday::Multipart::FilePart.new(media.path, media.mime_type, media.filename)
         @bot.api.send_video(chat_id: chat_id, video: file)
       end
 
+      # Upload and send a document file via the Telegram API
+      # @param chat_id [Integer] Telegram chat identifier
+      # @param media [Media::Item] document media item
       def send_document(chat_id, media)
         file = Faraday::Multipart::FilePart.new(media.path, media.mime_type, media.filename)
         @bot.api.send_document(chat_id: chat_id, document: file)
@@ -144,6 +168,8 @@ module Pocketrb
 
       private
 
+      # Process an incoming Telegram message: check allowlist, extract content, publish inbound
+      # @param message [Telegram::Bot::Types::Message] raw Telegram message object
       def handle_telegram_message(message)
         return unless message.is_a?(::Telegram::Bot::Types::Message)
         unless message.text || message.caption || message.photo || message.voice || message.document || message.audio || message.video
@@ -192,6 +218,9 @@ module Pocketrb
         @bus.publish_inbound(inbound)
       end
 
+      # Build a sender identifier string from a Telegram user
+      # @param user [Telegram::Bot::Types::User] Telegram user object
+      # @return [String] sender identifier combining user ID and username
       def build_sender_id(user)
         if user.username
           "#{user.id}|#{user.username}"
@@ -200,6 +229,9 @@ module Pocketrb
         end
       end
 
+      # Extract text content and media descriptions from a Telegram message
+      # @param message [Telegram::Bot::Types::Message] raw Telegram message object
+      # @return [String] combined text content
       def build_content(message)
         parts = []
         parts << message.text if message.text
@@ -219,6 +251,9 @@ module Pocketrb
         parts.empty? ? "[empty message]" : parts.join("\n")
       end
 
+      # Download all media attachments from a Telegram message
+      # @param message [Telegram::Bot::Types::Message] raw Telegram message object
+      # @return [Array<Media::Item>] downloaded media items
       def download_media(message)
         return [] unless @download_media
 
@@ -277,6 +312,12 @@ module Pocketrb
         media
       end
 
+      # Download a file from Telegram servers by file ID
+      # @param file_id [String] Telegram file identifier
+      # @param _type [Symbol] media type (unused, kept for interface consistency)
+      # @param mime_type [String] MIME type of the file
+      # @param filename [String, nil] optional filename override
+      # @return [Media::Item, nil] downloaded media item or nil on failure
       def download_telegram_file(file_id, _type, mime_type, filename = nil)
         # Get file path from Telegram
         result = @bot.api.get_file(file_id: file_id)
@@ -300,6 +341,9 @@ module Pocketrb
         nil
       end
 
+      # Check if a Telegram user is in the allowlist
+      # @param user [Telegram::Bot::Types::User] Telegram user to check
+      # @return [Boolean] true if user is allowed or no allowlist is configured
       def allowed_user?(user)
         return true if @allowed_users.nil? || @allowed_users.empty?
 
@@ -310,6 +354,9 @@ module Pocketrb
       end
 
       # Handle special commands that bypass the agent
+      # @param text [String] message text to check for commands
+      # @param chat_id [Integer] Telegram chat identifier for the reply
+      # @return [Boolean] true if a special command was handled
       def handle_special_command(text, chat_id)
         cmd = text.strip.split.first&.downcase
         return false unless SPECIAL_COMMANDS.include?(cmd)
@@ -334,6 +381,8 @@ module Pocketrb
         true
       end
 
+      # Build an HTML-formatted status overview for the /status command
+      # @return [String] HTML-formatted status text
       def build_status_response
         lines = []
         lines << "━━━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -388,14 +437,15 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Build an HTML-formatted list of background jobs for the /jobs command
+      # @return [String] HTML-formatted jobs text
       def build_jobs_response
         jobs_info = get_jobs_summary
         return "No background jobs." if jobs_info[:jobs].empty?
 
         lines = ["<b>📋 Background Jobs</b>", ""]
 
-        running = jobs_info[:all].select { |j| j[:running] }
-        completed = jobs_info[:all].reject { |j| j[:running] }
+        running, completed = jobs_info[:all].partition { |j| j[:running] }
 
         if running.any?
           lines << "<b>Running:</b>"
@@ -415,6 +465,8 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Build an HTML-formatted list of cron jobs for the /cron command
+      # @return [String] HTML-formatted cron jobs text
       def build_cron_response
         cron_info = get_cron_summary
         return "No scheduled jobs." if cron_info[:all].empty?
@@ -437,6 +489,8 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Build an HTML-formatted help text for the /help command
+      # @return [String] HTML-formatted help text
       def build_help_response
         <<~HELP
           <b>🤖 Pocketrb Commands</b>
@@ -455,6 +509,8 @@ module Pocketrb
         HELP
       end
 
+      # Detect running Claude CLI processes and return their status
+      # @return [Array<String>, nil] status lines or nil if no processes found
       def get_claude_cli_status
         # Check if claude processes are running
         claude_pids = `pgrep -f "claude" 2>/dev/null`.strip.split("\n")
@@ -492,6 +548,8 @@ module Pocketrb
         lines.empty? ? nil : lines.first(8)
       end
 
+      # Collect background job counts and descriptions
+      # @return [Hash] summary with :summary, :jobs, and :all keys
       def get_jobs_summary
         job_manager = @status_context[:job_manager]
 
@@ -517,6 +575,8 @@ module Pocketrb
         }
       end
 
+      # Collect cron job counts and descriptions
+      # @return [Hash] summary with :summary, :jobs, and :all keys
       def get_cron_summary
         cron_service = @status_context[:cron_service]
         return { summary: "N/A", jobs: [], all: [] } unless cron_service
@@ -531,6 +591,9 @@ module Pocketrb
         }
       end
 
+      # Format a duration in seconds as a human-readable uptime string
+      # @param seconds [Numeric] elapsed seconds
+      # @return [String] formatted uptime (e.g. "2h 30m")
       def format_uptime(seconds)
         seconds = seconds.to_i
         if seconds < 60
@@ -544,6 +607,9 @@ module Pocketrb
         end
       end
 
+      # Convert Markdown text to Telegram-compatible HTML
+      # @param text [String, nil] Markdown-formatted text
+      # @return [String] HTML-formatted text safe for Telegram
       def markdown_to_telegram_html(text)
         return "" if text.nil? || text.empty?
 

data/lib/pocketrb/channels/whatsapp.rb

@@ -5,8 +5,7 @@ require "socket"
 
 module Pocketrb
   module Channels
-    # WhatsApp channel via Node.js bridge WebSocket
-    # Connects to a whatsapp-web.js bridge running on localhost
+    # WhatsApp channel via Node.js bridge WebSocket. Connects to a whatsapp-web.js bridge running on localhost
     #
     # Bridge Protocol:
     # - Receive: {type: "message", sender: "...", content: "...", timestamp: ..., isGroup: bool}
@@ -14,9 +13,16 @@ module Pocketrb
     # - Status: {type: "status", status: "connected"}
     # - QR: {type: "qr", qr: "data:image/png;base64,..."}
     class WhatsApp < Base
+      # Delay in seconds before reconnecting after disconnect
       RECONNECT_DELAY = 5
+      # Default WebSocket bridge URL
       DEFAULT_BRIDGE_URL = "ws://localhost:3001"
 
+      # Initialize WhatsApp channel
+      # @param bus [Bus::MessageBus] Message bus for publishing and consuming messages
+      # @param bridge_url [String] WebSocket bridge URL (defaults to ws://localhost:3001)
+      # @param allowed_users [Array<String>, nil] Allowed phone numbers (nil = allow all)
+      # @param download_media [Boolean] Whether to download and process media attachments (defaults to true)
       def initialize(bus:, bridge_url: DEFAULT_BRIDGE_URL, allowed_users: nil, download_media: true)
         super(bus: bus, name: :whatsapp)
         @bridge_url = bridge_url
@@ -28,6 +34,7 @@ module Pocketrb
       end
 
       # Check if we can connect to the bridge
+      # @return [Boolean] true if the WebSocket client library is available
       def available?
         require "websocket-client-simple"
         true
@@ -35,11 +42,22 @@ module Pocketrb
         false
       end
 
+      # Start the channel
+      # @raise [MissingDependencyError] when the websocket-client-simple gem is not installed
+      def run
+        unless available?
+          raise MissingDependencyError,
+                "The WhatsApp channel needs the websocket-client-simple gem. " \
+                "Add `gem \"websocket-client-simple\"` to your Gemfile or run: gem install websocket-client-simple"
+        end
+
+        super
+      end
+
       protected
 
+      # Connect to the WhatsApp bridge and listen for inbound messages
       def run_inbound_loop
-        require "websocket-client-simple"
-
         Pocketrb.logger.info("Starting WhatsApp channel (bridge: #{@bridge_url})")
 
         loop do
@@ -56,11 +74,10 @@ module Pocketrb
             sleep RECONNECT_DELAY
           end
         end
-      rescue LoadError
-        Pocketrb.logger.error("websocket-client-simple gem not installed. Run: gem install websocket-client-simple")
-        raise
       end
 
+      # Send an outbound message via the WhatsApp WebSocket bridge
+      # @param message [Bus::OutboundMessage] outbound message to deliver
       def send_message(message)
         return unless @ws && @connected
 
@@ -79,6 +96,7 @@ module Pocketrb
 
       private
 
+      # Establish WebSocket connection and register event handlers
       def connect_and_listen
         channel = self
 
@@ -106,6 +124,8 @@ module Pocketrb
         sleep 0.5 while @ws.open? && @running
       end
 
+      # Route an incoming bridge WebSocket message by type
+      # @param data [String] raw JSON string from the bridge
       def handle_bridge_message(data)
         message = JSON.parse(data)
 
@@ -129,6 +149,8 @@ module Pocketrb
         Pocketrb.logger.warn("WhatsApp: invalid JSON: #{e.message}")
       end
 
+      # Process an incoming WhatsApp message and publish it to the bus
+      # @param message [Hash] parsed bridge message payload
       def handle_incoming_message(message)
         sender = extract_phone(message["sender"] || message["from"])
         return unless allowed_user?(sender)
@@ -171,6 +193,9 @@ module Pocketrb
         @bus.publish_inbound(inbound)
       end
 
+      # Download or decode media attached to a WhatsApp message
+      # @param message [Hash] parsed bridge message with media data
+      # @return [Media::Item, nil] processed media item or nil on failure
       def process_whatsapp_media(message)
         return nil unless message["mediaData"] || message["mediaUrl"]
 
@@ -191,6 +216,9 @@ module Pocketrb
         nil
       end
 
+      # Map a MIME type to a file extension
+      # @param mime_type [String] MIME type string
+      # @return [String] file extension without dot
       def extension_for_mime(mime_type)
         case mime_type
         when %r{^image/jpeg} then "jpg"
@@ -204,6 +232,8 @@ module Pocketrb
         end
       end
 
+      # Log a received QR code event from the bridge
+      # @param message [Hash] bridge message containing QR data
       def handle_qr(message)
         return unless message["qr"]
 
@@ -211,6 +241,9 @@ module Pocketrb
         # Could save to file or display in terminal if needed
       end
 
+      # Check if a phone number is in the allowlist
+      # @param phone [String] phone number to check
+      # @return [Boolean] true if allowed or no allowlist is configured
       def allowed_user?(phone)
         return true if @allowed_users.nil? || @allowed_users.empty?
 
@@ -218,6 +251,9 @@ module Pocketrb
         @allowed_users.any? { |allowed| normalize_phone(allowed) == normalized }
       end
 
+      # Convert a phone number to a WhatsApp JID
+      # @param phone [String] phone number or existing JID
+      # @return [String] WhatsApp JID (e.g. "1234@s.whatsapp.net")
       def to_jid(phone)
         return phone if phone.include?("@")
 
@@ -226,12 +262,18 @@ module Pocketrb
         "#{clean}@s.whatsapp.net"
       end
 
+      # Extract the phone number portion from a WhatsApp JID
+      # @param jid [String, nil] WhatsApp JID string
+      # @return [String, nil] phone number or original value
       def extract_phone(jid)
         return jid unless jid
 
         jid.split("@").first
       end
 
+      # Strip non-digit characters from a phone number for comparison
+      # @param phone [String, nil] phone number to normalize
+      # @return [String, nil] digits-only phone number or nil
       def normalize_phone(phone)
         return nil unless phone
 

data/lib/pocketrb/cli/chat.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "tty-spinner"
+
 module Pocketrb
   class CLI
     # Chat command - interactive chat mode
@@ -53,7 +55,12 @@ module Pocketrb
               content: input
             )
 
+            spinner = TTY::Spinner.new("[:spinner] Thinking...", format: :dots)
+            spinner.auto_spin
+
             response = agent_loop.process_message(msg)
+
+            spinner.stop
             puts "\n#{response.content}" if response
           end
         end

data/lib/pocketrb/cli/config.rb

@@ -5,6 +5,7 @@ module Pocketrb
     # Config command - manages configuration
     class Config < Thor
       desc "show", "Show current configuration"
+      # Display current configuration values
       def show
         workspace = options[:workspace] || Dir.pwd
         config = Pocketrb::Config.load(workspace)
@@ -18,6 +19,8 @@ module Pocketrb
       end
 
       desc "set KEY VALUE", "Set a configuration value"
+      # @param key [String] Configuration key to set
+      # @param value [String] Value to assign (will be auto-converted to int, float, or boolean if applicable)
       def set(key, value)
         workspace = options[:workspace] || Dir.pwd
         config = Pocketrb::Config.load(workspace)
@@ -36,6 +39,7 @@ module Pocketrb
       end
 
       desc "get KEY", "Get a configuration value"
+      # @param key [String] Configuration key to retrieve
       def get(key)
         workspace = options[:workspace] || Dir.pwd
         config = Pocketrb::Config.load(workspace)

data/lib/pocketrb/cli/cron.rb

@@ -6,6 +6,7 @@ module Pocketrb
     class Cron < Thor
       desc "list", "List scheduled jobs"
       option :all, type: :boolean, aliases: "-a", desc: "Include disabled jobs"
+      # List all scheduled cron jobs
       def list
         workspace = Pathname.new(options[:workspace] || Dir.pwd).expand_path
         cron_store = workspace.join(".pocketrb", "data", "cron", "jobs.json")
@@ -38,6 +39,7 @@ module Pocketrb
       option :deliver, type: :boolean, default: false, desc: "Deliver to channel instead of processing"
       option :channel, type: :string, desc: "Target channel for delivery"
       option :to, type: :string, desc: "Target chat ID for delivery"
+      # Add a new scheduled cron job
       def add
         workspace = Pathname.new(options[:workspace] || Dir.pwd).expand_path
         cron_store = workspace.join(".pocketrb", "data", "cron", "jobs.json")
@@ -84,6 +86,7 @@ module Pocketrb
       end
 
       desc "remove JOB_ID", "Remove a scheduled job"
+      # @param job_id [String] Job identifier to remove
       def remove(job_id)
         workspace = Pathname.new(options[:workspace] || Dir.pwd).expand_path
         cron_store = workspace.join(".pocketrb", "data", "cron", "jobs.json")
@@ -101,6 +104,7 @@ module Pocketrb
       end
 
       desc "enable JOB_ID", "Enable a scheduled job"
+      # @param job_id [String] Job identifier to enable
       def enable(job_id)
         workspace = Pathname.new(options[:workspace] || Dir.pwd).expand_path
         cron_store = workspace.join(".pocketrb", "data", "cron", "jobs.json")
@@ -118,6 +122,7 @@ module Pocketrb
       end
 
       desc "disable JOB_ID", "Disable a scheduled job"
+      # @param job_id [String] Job identifier to disable
       def disable(job_id)
         workspace = Pathname.new(options[:workspace] || Dir.pwd).expand_path
         cron_store = workspace.join(".pocketrb", "data", "cron", "jobs.json")
@@ -135,6 +140,7 @@ module Pocketrb
       end
 
       desc "trigger JOB_ID", "Trigger a job manually"
+      # @param _job_id [String] Job identifier to trigger (unused in current implementation)
       def trigger(_job_id)
         say "Manual job execution requires running gateway", :yellow
         say "Use 'pocketrb gateway' and the job will be executed", :yellow

data/lib/pocketrb/cli.rb

@@ -2,7 +2,6 @@
 
 require "thor"
 
-# Main namespace for Pocketrb gem
 module Pocketrb
   # Command-line interface
   class CLI < Thor