ai-toolbox

/**
 * System prompt documentation for LLM - describes all available tools
 */

import type { PluginConfig } from './config';

export class ToolsDocumentation {
  /**
   * Get documentation string for enabled tools based on config
   */
  static getEnabledDocs(config: PluginConfig): string {
    const sections: string[] = [];
    
    if (config.fileSystem) {
      sections.push(this.getFileSystemDocs());
    }
    if (config.webSearch) {
      sections.push(this.getWebResearchDocs());
    }
    if (config.browserAutomation) {
      sections.push(this.getBrowserDocs());
    }
    if (config.gitOperations) {
      sections.push(this.getGitDocs());
    }
    if (config.databaseQueries) {
      sections.push(this.getDatabaseDocs());
    }
    if (config.documentParsing) {
      sections.push(this.getDocumentParsingDocs());
    }
    if (config.backgroundCommands) {
      sections.push(this.getBackgroundCommandDocs());
    }
    if (config.executionJavaScript || config.executionPython || 
        config.executionTerminal || config.executionShell) {
      sections.push(this.getExecutionDocs());
    }
    
    return sections.join('\n\n---\n\n');
  }

  /**
   * File System Tools Documentation (~17 tools)
   */
  static getFileSystemDocs(): string {
    return `
### 📁 FILE SYSTEM TOOLS (17)

**list_directory(path)** - List files/folders in workspace or subdirectory
- Parameters: path (string, optional)
- Returns: Array of file/directory names

**read_file(file_name)** - Read text file content
- Parameters: file_name (string)
- Returns: File content string

**save_file(file_name, content)** - Create/overwrite file (supports batch save)
- Parameters: file_name (string), content (string), files (array for batch)
- Returns: Full path to saved file

**replace_text_in_file(file_name, old_string, new_string)** - Replace exact string in file
- Parameters: file_name, old_string (must match exactly), new_string
- Returns: Success/failure status

**insert_at_line(file_name, line_number, content_to_insert)** - Insert text at specific line
- Parameters: file_name, line_number (1-indexed), content_to_insert
- Existing content pushed down

**append_file(file_name, content)** - Append to end of file (creates if missing)
- Parameters: file_name, content

**delete_lines_in_file(file_name, start_line, end_line?)** - Delete specific lines
- Parameters: file_name, start_line (1-indexed), end_line (optional, inclusive)

**make_directory(directory_name)** - Create new directory
- Parameters: directory_name

**move_file(source, destination)** - Move/rename file or directory
- Parameters: source, destination

**copy_file(source, destination)** - Copy file to new location
- Parameters: source, destination

**delete_path(path)** - Delete file/directory (destructive!)
- Parameters: path

**delete_files_by_pattern(pattern)** - Delete files matching regex pattern
- Parameters: pattern (regex string)

**find_files(pattern, max_depth?)** - Find files by name pattern recursively
- Parameters: pattern (substring), max_depth (optional, default 5)

**fuzzy_find_local_files(query, path?, max_results?)** - Fuzzy search by name/path similarity
- Parameters: query, path (sub-directory), max_results (default 5)

**get_file_metadata(path)** - Get file size, dates, type info
- Parameters: path

**change_directory(directory)** - Change working directory
- Parameters: directory
- Returns: New current directory

**read_document(file_path)** - Read PDF/DOCX documents
- Parameters: file_path (PDF or DOCX)

**analyze_project(categories?, max_imports_warning?)** — Comprehensive TypeScript performance & linting analysis
- Parameters: categories (array of 'typecheck'|'circular'|'eslint'|'config'|'imports', default: all), max_imports_warning (default: 20)
- Runs: tsc --extendedDiagnostics, madge circular dependency detection, ESLint, tsconfig optimization checks, import structure analysis
- Returns: Structured results per category with performance assessment and recommendations
`;
  }

  /**
   * Web & Research Tools Documentation (~7 tools)
   */
  static getWebResearchDocs(): string {
    return `
### 🌐 WEB & RESEARCH TOOLS (7)

**web_search(query, providers?)** - Search DuckDuckGo/Google/Bing with fallback chain
- Parameters: query (string), providers (optional array)
- Fallback: DDG Fetch → DDG API → DDG browser → Google → Bing

**wikipedia_search(query, lang?)** - Search Wikipedia for summaries
- Parameters: query, lang (language code, default 'en')

**fetch_web_content(url)** - Fetch webpage clean text content
- Parameters: url (HTTP/HTTPS)

**rag_web_content(url, query)** - RAG-based semantic web search
- Parameters: url, query
- Returns: Most relevant text chunks

**browser_session_open(url, wait_for_selector?, include_page_text?)** - Open persistent browser session
- Parameters: url, selector (optional), page text flag
- Returns: Page text content

**browser_session_control(actions?, read_page?, full_read?, screenshot_path?)** - Control browser actions
- Actions: wait_for_selector, wait, click, type, press, select, hover, scroll, evaluate
- Parameters: action array, page read flags, screenshot path

**browser_session_close()** - Close active browser session
`;
  }

  /**
   * Git & GitHub Tools Documentation (~13 tools)
   */
  static getGitDocs(): string {
    return `
### 🐙 GIT & GITHUB TOOLS (13)

**git_status()** - View modified files in repository
- Returns: Status summary

**git_diff(file_path?, cached?)** - See changes in detail
- Parameters: file_path (optional), cached (staged only)

**git_commit(message)** - Commit staged changes
- Parameters: message

**git_log(max_count?)** - View commit history
- Parameters: max_count (default 10)

**git_add(paths?)** - Stage specific files or all changes
- Parameters: paths (optional array)

**git_checkout(branch_name, create_new?)** - Switch/create branches
- Parameters: branch_name, create_new flag (-b equivalent)

**gh_auth()** - Check GitHub authentication status
- Opens terminal for sign-in if not authenticated

**gh_create_issue(title, body?, labels?)** - Create new GitHub issue
- Parameters: title (required), body, labels

**gh_list_issues(state?, labels?, limit?)** - List issues in repository
- Parameters: state (open/closed), labels, limit (default 10)

**gh_view_comments(number, type?)** - View comments on issue/PR
- Parameters: number, type ('issue' or 'pr')

**gh_create_pr(title, body, head_branch, base_branch?)** - Create pull request
- Parameters: title, body, head_branch (required), base_branch (default 'main')

**gh_list_prs(state?, limit?)** - List pull requests
- Parameters: state, limit

**gh_view_pr_diff(number)** - Fetch PR diff/patch
- Parameters: PR number

**gh_push(branch?)** - Push commits to remote
- Parameters: branch (optional)
`;
  }

  /**
   * Browser Automation Documentation (~3 tools)
   */
  static getBrowserDocs(): string {
    return `
### 🌐 BROWSER AUTOMATION TOOLS (3)

**browser_open_page(url, screenshot_path?, wait_for_selector?, actions?)** - One-shot page render with Puppeteer
- Parameters: url, screenshot path, selector to wait for, scripted actions array
- Actions include: click, type, press, evaluate (JavaScript), scroll, hover
- Returns: Page content after rendering

Note: This is a one-shot tool. Do not use for multi-step navigation. Use browser_session_open for persistent sessions.
`;
  }

  /**
   * Database Query Documentation (~1 tool)
   */
  static getDatabaseDocs(): string {
    return `
### 💾 DATABASE QUERY TOOLS (1)

**query_database(query)** - Run read-only SQLite queries
- Parameters: query (SQL string)
- Returns: Query results
- Note: Read-only operations only, no write/modify allowed
`;
  }

  /**
   * Document Parsing Documentation (~1 tool)
   */
  static getDocumentParsingDocs(): string {
    return `
### 📄 DOCUMENT PARSING TOOLS (1)

**read_document(file_path)** - Read PDF or DOCX documents
- Parameters: file_path (PDF or DOCX format)
- Returns: Extracted text content

Supports:
- PDF files via pdf-parse library
- DOCX files via mammoth library
`;
  }

  /**
   * Background Command Documentation (~3 tools)
   */
  static getBackgroundCommandDocs(): string {
    return `
### ⏱️ BACKGROUND COMMAND TOOLS (3)

**run_background_command(command, timeout_hours, name)** - Start long-running process in background
- Parameters: command (string), timeout_hours (mandatory, max 10), name (descriptive)
- Process runs unblocked, must provide timeout and name

**check_background_command(id)** - Check status, stdout, stderr of running/completed command
- Parameters: id (command identifier)

**cancel_background_command(id)** - Kill a running background command
- Parameters: id
`;
  }

  /**
   * Execution Tools Documentation (~3 tools)
   */
  static getExecutionDocs(): string {
    return `
### 💻 EXECUTION TOOLS (3)

**run_javascript(javascript, timeout_seconds?)** - Run JavaScript code snippet using deno (sandboxed)
- Parameters: javascript (string), timeout_seconds (optional, max 60)
- Returns: stdout and stderr output
- Note: Runs in sandboxed environment, no external module imports allowed

**run_python(python, timeout_seconds?)** - Run Python code snippet (sandboxed, no external modules)
- Parameters: python (string), timeout_seconds (optional, max 60)  
- Returns: stdout and stderr output
- Note: Standard library only, no pip packages allowed

**execute_command(command, timeout_seconds?)** - Execute shell command in current working directory
- Parameters: command (string), timeout_seconds (optional, max 60)
- Returns: stdout and stderr output
- Security: Dangerous patterns like 'rm -rf' are blocked
`;
  }
}