pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/tools/browser.rb

@@ -6,14 +6,20 @@ module Pocketrb
   module Tools
     # Browser automation tool using Playwright
     class Browser < Base
+      # Tool name
+      # @return [String]
       def name
         "browser"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Automate browser interactions using headless Chromium. Can navigate to URLs, extract text content, take screenshots, interact with elements, and execute JavaScript. Use this for web scraping, research, testing, or any task requiring web browsing."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -52,6 +58,16 @@ module Pocketrb
         }
       end
 
+      # Execute browser automation action
+      # @param action [String] Action to perform (navigate, extract_text, screenshot, click, type, execute_js)
+      # @param url [String, nil] URL to navigate to
+      # @param selector [String, nil] CSS selector for element targeting
+      # @param text [String, nil] Text to type into an element
+      # @param javascript [String, nil] JavaScript code to execute in browser context
+      # @param screenshot_path [String, nil] File path for saving screenshot
+      # @param wait_time [Integer] Milliseconds to wait after navigation
+      # @option _kwargs [Object] * Additional action-specific options
+      # @return [String] Action result
       def execute(action:, url: nil, selector: nil, text: nil, javascript: nil, screenshot_path: nil, wait_time: 1000,
                   **_kwargs)
         case action
@@ -86,6 +102,9 @@ module Pocketrb
 
       private
 
+      # Launch headless browser and yield the page
+      # @yield [Playwright::Page] browser page instance
+      # @return [Object] result of the block
       def with_browser
         Playwright.create(playwright_cli_executable_path: "npx playwright") do |playwright|
           playwright.chromium.launch(headless: true) do |browser|
@@ -98,6 +117,10 @@ module Pocketrb
         @current_page = nil
       end
 
+      # Navigate to URL and extract page content
+      # @param url [String] URL to navigate to
+      # @param wait_time [Integer] milliseconds to wait after navigation
+      # @return [String] page title and text content
       def navigate_and_extract(url, wait_time)
         with_browser do |page|
           page.goto(url)
@@ -110,6 +133,8 @@ module Pocketrb
         end
       end
 
+      # Extract text content from the currently loaded page
+      # @return [String] page text content or error if no page is loaded
       def extract_text_from_page
         return error("No page is currently loaded. Use navigate action first.") unless @current_page
 
@@ -117,6 +142,9 @@ module Pocketrb
         success(content[0..5000] + (content.length > 5000 ? "...(truncated)" : ""))
       end
 
+      # Take a screenshot and save to the given path
+      # @param path [String] file path to save the screenshot
+      # @return [String] confirmation message
       def take_screenshot(path)
         with_browser do |page|
           screenshot_path = resolve_path(path)
@@ -125,6 +153,10 @@ module Pocketrb
         end
       end
 
+      # Click an element matching the selector
+      # @param selector [String] CSS selector for the element
+      # @param wait_time [Integer] milliseconds to wait after clicking
+      # @return [String] confirmation message
       def click_element(selector, wait_time)
         with_browser do |page|
           page.click(selector)
@@ -133,6 +165,11 @@ module Pocketrb
         end
       end
 
+      # Type text into an element matching the selector
+      # @param selector [String] CSS selector for the input element
+      # @param text [String] content to fill into the input element
+      # @param wait_time [Integer] milliseconds to wait after typing
+      # @return [String] confirmation message
       def type_into_element(selector, text, wait_time)
         with_browser do |page|
           page.fill(selector, text)
@@ -141,6 +178,9 @@ module Pocketrb
         end
       end
 
+      # Execute JavaScript code in the browser page context
+      # @param javascript [String] JavaScript code to evaluate
+      # @return [String] execution result
       def execute_javascript(javascript)
         with_browser do |page|
           result = page.evaluate(javascript)

data/lib/pocketrb/tools/browser_advanced.rb

@@ -6,6 +6,7 @@ module Pocketrb
   module Tools
     # Enhanced browser tool with sessions and tabs
     class BrowserAdvanced < Base
+      # Available browser actions
       ACTIONS = %w[
         new_tab close_tab focus_tab list_tabs
         navigate back forward refresh
@@ -17,10 +18,14 @@ module Pocketrb
         press_key
       ].freeze
 
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "browser"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         <<~DESC.strip
           Browse the web with a persistent browser session. Supports multiple tabs,
@@ -29,6 +34,8 @@ module Pocketrb
         DESC
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema for tool parameters
       def parameters
         {
           type: "object",
@@ -88,11 +95,23 @@ module Pocketrb
         }
       end
 
+      # Check if Playwright is available
+      # @return [Boolean] True if npx or playwright command is found
       def available?
         # Check if playwright is available
         system("which npx > /dev/null 2>&1") || system("which playwright > /dev/null 2>&1")
       end
 
+      # Execute browser operation
+      # @param action [String] Action to perform (new_tab, close_tab, focus_tab, list_tabs, navigate, etc.)
+      # @option args [String] :url URL for navigation or new tab
+      # @option args [String] :tab_id Tab identifier
+      # @option args [String] :selector CSS/XPath selector
+      # @option args [String] :text Text to type
+      # @option args [String] :key Key to press
+      # @option args [String] :javascript JavaScript code to execute
+      # @option args [Hash] :options Additional action-specific options
+      # @return [String] JSON result of operation
       def execute(action:, **args)
         case action
         # Tab management
@@ -160,10 +179,15 @@ module Pocketrb
 
       private
 
+      # Access the browser session singleton
+      # @return [BrowserSession]
       def session
         BrowserSession.instance
       end
 
+      # Get the Playwright page for a tab
+      # @param tab_id [String, nil] tab identifier, uses active tab if nil
+      # @return [Playwright::Page, nil]
       def page(tab_id = nil)
         if tab_id
           session.tabs[tab_id]&.dig(:page)
@@ -172,6 +196,8 @@ module Pocketrb
         end
       end
 
+      # Get active page, creating a new tab if none exists
+      # @return [Playwright::Page]
       def ensure_page!
         p = page
         return p if p
@@ -181,8 +207,9 @@ module Pocketrb
         session.active_page
       end
 
-      # === Tab Management ===
-
+      # Open a new browser tab, optionally navigating to a URL
+      # @param url [String, nil] URL to load in the new tab
+      # @return [String] confirmation with tab ID
       def new_tab(url)
         tab_id = session.new_tab(url: url)
         info = session.tab_info(tab_id)
@@ -194,6 +221,9 @@ module Pocketrb
         end
       end
 
+      # Close a browser tab
+      # @param tab_id [String, nil] tab identifier, uses active tab if nil
+      # @return [String] confirmation or error message
       def close_tab(tab_id)
         tab_id ||= session.active_tab_id
         return error("No tab to close") unless tab_id
@@ -206,6 +236,9 @@ module Pocketrb
         end
       end
 
+      # Switch focus to a specific tab
+      # @param tab_id [String] tab identifier to focus
+      # @return [String] confirmation or error message
       def focus_tab(tab_id)
         return error("Tab ID required") unless tab_id
 
@@ -217,6 +250,8 @@ module Pocketrb
         end
       end
 
+      # List all open browser tabs
+      # @return [String] formatted list of open tabs
       def list_tabs
         tabs = session.list_tabs
         return "No tabs open. Use action 'new_tab' to open one." if tabs.empty?
@@ -232,6 +267,10 @@ module Pocketrb
 
       # === Navigation ===
 
+      # Navigate to URL
+      # @param url [String] URL to navigate to
+      # @option options [String] :wait_until Wait condition (load, domcontentloaded, networkidle)
+      # @return [String] Success message
       def navigate(url, options)
         return error("URL required") unless url
 
@@ -245,6 +284,8 @@ module Pocketrb
         success("Navigated to: #{title}\nURL: #{p.url}")
       end
 
+      # Navigate back in browser history
+      # @return [String] confirmation message
       def go_back
         p = ensure_page!
         p.go_back
@@ -252,6 +293,8 @@ module Pocketrb
         success("Navigated back to: #{p.title}")
       end
 
+      # Navigate forward in browser history
+      # @return [String] confirmation message
       def go_forward
         p = ensure_page!
         p.go_forward
@@ -259,6 +302,8 @@ module Pocketrb
         success("Navigated forward to: #{p.title}")
       end
 
+      # Reload the current page
+      # @return [String] confirmation message
       def refresh_page
         p = ensure_page!
         p.reload
@@ -267,6 +312,10 @@ module Pocketrb
 
       # === Interaction ===
 
+      # Click an element
+      # @param selector [String] CSS or XPath selector
+      # @option options [Integer] :timeout Timeout in milliseconds
+      # @return [String] Success message
       def click_element(selector, options)
         return error("Selector required") unless selector
 
@@ -277,6 +326,11 @@ module Pocketrb
         success("Clicked: #{selector}")
       end
 
+      # Type text into an element
+      # @param selector [String] CSS or XPath selector
+      # @param text [String] content to fill into the input element
+      # @param _options [Hash] additional options (unused)
+      # @return [String] confirmation or error message
       def type_text(selector, text, _options)
         return error("Selector and text required") unless selector && text
 
@@ -286,6 +340,9 @@ module Pocketrb
         success("Typed into #{selector}: #{text[0..50]}#{"..." if text.length > 50}")
       end
 
+      # Hover over an element
+      # @param selector [String] CSS or XPath selector
+      # @return [String] confirmation or error message
       def hover_element(selector)
         return error("Selector required") unless selector
 
@@ -294,6 +351,10 @@ module Pocketrb
         success("Hovering over: #{selector}")
       end
 
+      # Scroll the page to a position or element
+      # @param direction [String, nil] scroll target: top, bottom, or element
+      # @param selector [String, nil] CSS selector when scrolling to element
+      # @return [String] confirmation or error message
       def scroll_page(direction, selector)
         p = ensure_page!
 
@@ -315,6 +376,10 @@ module Pocketrb
         end
       end
 
+      # Press a keyboard key, optionally targeting an element
+      # @param key [String] key to press (e.g. Enter, Tab, Escape)
+      # @param selector [String, nil] CSS selector to target, uses keyboard if nil
+      # @return [String] confirmation or error message
       def press_key(key, selector)
         return error("Key required") unless key
 
@@ -329,6 +394,9 @@ module Pocketrb
         success("Pressed key: #{key}")
       end
 
+      # Fill multiple form fields at once
+      # @param form_data [Hash] mapping of CSS selectors to values
+      # @return [String] confirmation or error message
       def fill_form(form_data)
         return error("Form data required") unless form_data.is_a?(Hash)
 
@@ -343,6 +411,10 @@ module Pocketrb
         success("Filled #{filled.size} form fields: #{filled.join(", ")}")
       end
 
+      # Select an option from a dropdown element
+      # @param selector [String] CSS selector for the select element
+      # @param value [String] option value to select
+      # @return [String] confirmation or error message
       def select_option(selector, value)
         return error("Selector and value required") unless selector && value
 
@@ -351,8 +423,9 @@ module Pocketrb
         success("Selected '#{value}' in #{selector}")
       end
 
-      # === Content ===
-
+      # Take a screenshot of the current page
+      # @param full_page [Boolean, nil] whether to capture the full scrollable page
+      # @return [String] path to saved screenshot
       def take_screenshot(full_page)
         p = ensure_page!
 
@@ -364,6 +437,8 @@ module Pocketrb
         success("Screenshot saved: #{path}")
       end
 
+      # Get a text snapshot of the page including content and interactive elements
+      # @return [String] formatted page snapshot
       def get_snapshot
         p = ensure_page!
 
@@ -428,6 +503,9 @@ module Pocketrb
         SNAPSHOT
       end
 
+      # Get text content from an element or the entire page
+      # @param selector [String, nil] CSS selector, defaults to body if nil
+      # @return [String] element text content
       def get_text(selector)
         p = ensure_page!
 
@@ -437,6 +515,10 @@ module Pocketrb
         success(text)
       end
 
+      # Get an HTML attribute value from an element
+      # @param selector [String] CSS selector for the element
+      # @param attribute [String] attribute name to retrieve
+      # @return [String] attribute value or error message
       def get_attribute(selector, attribute)
         return error("Selector and attribute required") unless selector && attribute
 
@@ -445,6 +527,9 @@ module Pocketrb
         success("#{selector}[#{attribute}] = #{value}")
       end
 
+      # Execute JavaScript code in the browser context
+      # @param code [String] JavaScript code to evaluate
+      # @return [String] execution result or error message
       def execute_javascript(code)
         return error("JavaScript code required") unless code
 
@@ -455,6 +540,11 @@ module Pocketrb
 
       # === Wait ===
 
+      # Wait for selector to appear
+      # @param selector [String] CSS or XPath selector to wait for
+      # @option options [Integer] :timeout Timeout in milliseconds
+      # @option options [String] :state Element state to wait for (visible, hidden, attached, detached)
+      # @return [String] Success message
       def wait_for(selector, options)
         return error("Selector required") unless selector
 

data/lib/pocketrb/tools/browser_session.rb

@@ -21,6 +21,8 @@ module Pocketrb
         @started = false
       end
 
+      # Start the browser session
+      # @return [void]
       def start!
         return if @started
 
@@ -42,6 +44,8 @@ module Pocketrb
         end
       end
 
+      # Stop the browser session and cleanup
+      # @return [void]
       def stop!
         @mutex.synchronize do
           @tabs.each_value do |tab|
@@ -62,11 +66,15 @@ module Pocketrb
         end
       end
 
+      # Check if browser session is running
+      # @return [Boolean] True if browser is started
       def started?
         @started
       end
 
       # Create a new tab
+      # @param url [String, nil] Initial URL to navigate to
+      # @return [String] Tab identifier
       def new_tab(url: nil)
         start! unless started?
 
@@ -90,6 +98,8 @@ module Pocketrb
       end
 
       # Close a tab
+      # @param tab_id [String] Tab identifier to close
+      # @return [Boolean] True if tab was closed successfully
       def close_tab(tab_id)
         @mutex.synchronize do
           tab = @tabs.delete(tab_id)
@@ -102,6 +112,8 @@ module Pocketrb
       end
 
       # Focus a tab
+      # @param tab_id [String] Tab identifier to focus
+      # @return [Boolean] True if tab was focused successfully
       def focus_tab(tab_id)
         @mutex.synchronize do
           return false unless @tabs.key?(tab_id)
@@ -120,6 +132,8 @@ module Pocketrb
       end
 
       # Get tab info
+      # @param tab_id [String] Tab identifier
+      # @return [Hash, nil] Tab information hash or nil if not found
       def tab_info(tab_id)
         tab = @tabs[tab_id]
         return nil unless tab
@@ -145,6 +159,8 @@ module Pocketrb
       end
 
       # Update tab metadata
+      # @param tab_id [String] Tab identifier
+      # @return [void]
       def update_tab_info(tab_id)
         tab = @tabs[tab_id]
         return unless tab
@@ -155,6 +171,8 @@ module Pocketrb
 
       private
 
+      # Locate the Playwright CLI executable
+      # @return [String] path or command to run Playwright
       def find_playwright_cli
         # Try common locations
         ["npx playwright", "playwright", "node_modules/.bin/playwright"].each do |cmd|

data/lib/pocketrb/tools/cron.rb

@@ -6,10 +6,14 @@ module Pocketrb
   module Tools
     # Manage scheduled cron jobs - allows agent to be proactive
     class Cron < Base
+      # Tool name
+      # @return [String] Tool identifier
       def name
         "cron"
       end
 
+      # Tool description
+      # @return [String] Human-readable description
       def description
         <<~DESC.strip
           Manage scheduled tasks. Create reminders, follow-ups, or recurring checks.
@@ -17,6 +21,8 @@ module Pocketrb
         DESC
       end
 
+      # Tool parameters schema
+      # @return [Hash] JSON schema for tool parameters
       def parameters
         {
           type: "object",
@@ -56,10 +62,21 @@ module Pocketrb
         }
       end
 
+      # Check if cron service is available
+      # @return [Boolean] True if cron service is configured
       def available?
         !cron_service.nil?
       end
 
+      # Execute cron operation
+      # @param action [String] Action to perform (add, list, remove, enable, disable)
+      # @param name [String, nil] Job name (for add action)
+      # @param message [String, nil] Job message/task (for add action)
+      # @param schedule_type [String, nil] Schedule type: "at", "every", or "cron" (for add action)
+      # @param schedule_value [String, Integer, nil] Schedule value based on type (for add action)
+      # @param job_id [String, nil] Job identifier (for remove/enable/disable actions)
+      # @param deliver [Boolean] Whether to deliver message via channel (defaults to true)
+      # @return [String] JSON result of operation
       def execute(action:, name: nil, message: nil, schedule_type: nil, schedule_value: nil, job_id: nil, deliver: true)
         return error("Cron service not available. Start with --enable-cron flag.") unless cron_service
 
@@ -81,18 +98,31 @@ module Pocketrb
 
       private
 
+      # Access cron service from context
+      # @return [Object, nil]
       def cron_service
         @context[:cron_service]
       end
 
+      # Get the default output channel
+      # @return [Symbol]
       def current_channel
         @context[:default_channel] || @context[:channel] || :telegram
       end
 
+      # Get the default chat identifier
+      # @return [String, nil]
       def current_chat_id
         @context[:default_chat_id] || @context[:chat_id]
       end
 
+      # Add a new scheduled job
+      # @param name [String] job name
+      # @param message [String] message to deliver when job runs
+      # @param schedule_type [String] schedule kind: at, every, or cron
+      # @param schedule_value [String] schedule value matching the type
+      # @param deliver [Boolean] whether to deliver message to channel
+      # @return [String] confirmation or error message
       def add_job(name, message, schedule_type, schedule_value, deliver)
         return error("Name required") unless name && !name.empty?
         return error("Message required") unless message && !message.empty?
@@ -116,6 +146,10 @@ module Pocketrb
         success("Created job '#{name}' (ID: #{job.id}). Next run: #{next_run_time || "pending"}")
       end
 
+      # Build a Schedule object from type and value
+      # @param type [String] schedule kind: at, every, or cron
+      # @param value [String, nil] schedule value for the given type
+      # @return [Pocketrb::Cron::Schedule, String] schedule object or error string
       def build_schedule(type, value)
         case type
         when "at"
@@ -151,6 +185,8 @@ module Pocketrb
         end
       end
 
+      # List all scheduled jobs with status and next run time
+      # @return [String] formatted list of jobs
       def list_jobs
         jobs = cron_service.list_jobs(include_disabled: true)
 
@@ -177,6 +213,9 @@ module Pocketrb
         lines.join("\n")
       end
 
+      # Format a schedule object into a human-readable string
+      # @param schedule [Pocketrb::Cron::Schedule] schedule object containing kind and timing details
+      # @return [String] human-readable schedule description
       def format_schedule(schedule)
         case schedule.kind
         when :at
@@ -198,6 +237,9 @@ module Pocketrb
         end
       end
 
+      # Remove a scheduled job
+      # @param job_id [String] job identifier
+      # @return [String] confirmation or error message
       def remove_job(job_id)
         return error("Job ID required") unless job_id
 
@@ -208,6 +250,10 @@ module Pocketrb
         end
       end
 
+      # Enable or disable a scheduled job
+      # @param job_id [String] job identifier
+      # @param enabled [Boolean] true to enable, false to disable
+      # @return [String] confirmation or error message
       def toggle_job(job_id, enabled)
         return error("Job ID required") unless job_id
 

data/lib/pocketrb/tools/edit_file.rb

@@ -4,14 +4,20 @@ module Pocketrb
   module Tools
     # Edit a file with search/replace
     class EditFile < Base
+      # Tool name
+      # @return [String]
       def name
         "edit_file"
       end
 
+      # Tool description
+      # @return [String]
       def description
         "Edit a file by replacing specific text. The old_string must match exactly (including whitespace and indentation). Use for precise edits rather than rewriting entire files."
       end
 
+      # Parameter schema
+      # @return [Hash]
       def parameters
         {
           type: "object",
@@ -37,6 +43,12 @@ module Pocketrb
         }
       end
 
+      # Execute file edit operation
+      # @param path [String] File path to edit
+      # @param old_string [String] Exact text to find
+      # @param new_string [String] Replacement text
+      # @param replace_all [Boolean] Whether to replace all occurrences
+      # @return [String] Success or error message
       def execute(path:, old_string:, new_string:, replace_all: false)
         resolved = validate_path!(path)
 
@@ -75,6 +87,10 @@ module Pocketrb
 
       private
 
+      # Suggest similar content when old_string is not found
+      # @param content [String] full file content
+      # @param old_string [String] text that was not found
+      # @return [String] suggestion message with closest matches
       def suggest_match(content, old_string)
         # Try to find similar content
         lines = content.lines