droid-patch 0.1.1 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # droid-patch
 
+English | [简体中文](./README.zh-CN.md)
+
 CLI tool to patch the droid binary with various modifications.
 
 ## Installation
@@ -12,20 +14,39 @@ npx droid-patch --help
 
 ## Usage
 
-### Patch and create an alias
+### Patch and Create an Alias
 
 ```bash
-# Patch the default droid binary and create an alias
-npx droid-patch --is-custom droid
+# Patch with --is-custom and create an alias
+npx droid-patch --is-custom droid-custom
+
+# Patch with --skip-login to bypass login requirement
+npx droid-patch --skip-login droid-nologin
+
+# Patch with --websearch to enable local search proxy
+npx droid-patch --websearch droid-search
+
+# Combine multiple patches
+npx droid-patch --is-custom --skip-login --websearch droid-full
 
 # Specify a custom path to the droid binary
-npx droid-patch --is-custom -p /path/to/droid my-droid
+npx droid-patch --skip-login -p /path/to/droid my-droid
 
 # Dry run - verify patches without actually applying them
-npx droid-patch --is-custom --dry-run droid
+npx droid-patch --skip-login --dry-run droid
 
 # Verbose output
-npx droid-patch --is-custom -v droid
+npx droid-patch --skip-login -v droid
+```
+
+### Output to a Specific Directory
+
+```bash
+# Output patched binary to current directory
+npx droid-patch --skip-login -o . my-droid
+
+# Output to a specific directory
+npx droid-patch --skip-login -o /path/to/dir my-droid
 ```
 
 ### Available Options
@@ -33,13 +54,16 @@ npx droid-patch --is-custom -v droid
 | Option | Description |
 |--------|-------------|
 | `--is-custom` | Patch `isCustom:!0` to `isCustom:!1` (enables context compression for custom models) |
+| `--skip-login` | Bypass login by injecting a fake `FACTORY_API_KEY` into the binary |
+| `--api-base <url>` | Replace Factory API URL with a custom server (max 22 chars) |
+| `--websearch` | Inject local WebSearch proxy with multiple search providers |
 | `--dry-run` | Verify patches without actually modifying the binary |
 | `-p, --path <path>` | Path to the droid binary (default: `~/.droid/bin/droid`) |
-| `-o, --output <path>` | Output path for patched binary (default: `<path>.patched`) |
+| `-o, --output <dir>` | Output directory for patched binary (creates file without alias) |
 | `--no-backup` | Skip creating backup of original binary |
 | `-v, --verbose` | Enable verbose output |
 
-### Manage Aliases
+### Manage Aliases and Files
 
 ```bash
 # List all aliases
@@ -47,25 +71,39 @@ npx droid-patch list
 
 # Remove an alias
 npx droid-patch remove <alias-name>
+
+# Remove a patched binary file by path
+npx droid-patch remove ./my-droid
+npx droid-patch remove /path/to/patched-binary
+
+# Check proxy status
+npx droid-patch proxy-status
+```
+
+### Check Version
+
+```bash
+npx droid-patch version
 ```
 
 ## PATH Configuration
 
-After creating an alias, you need to add the aliases directory to your PATH:
+When creating an alias (without `-o`), the tool will try to install to a directory already in your PATH (like `~/.local/bin`). If not available, you need to add the aliases directory to your PATH:
 
 ```bash
 # Add to your shell config (~/.zshrc, ~/.bashrc, etc.)
 export PATH="$HOME/.droid-patch/aliases:$PATH"
 ```
 
-Or run the quick setup command shown after patching.
-
 ## How It Works
 
-1. **Patching**: The tool searches for specific byte patterns in the droid binary and replaces them
-2. **Alias Creation**:
+1. **Patching**: The tool searches for specific byte patterns in the droid binary and replaces them with equal-length replacements
+2. **Alias Creation** (without `-o`):
    - Copies the patched binary to `~/.droid-patch/bins/`
-   - Creates a symlink in `~/.droid-patch/aliases/`
+   - Creates a symlink in a PATH directory or `~/.droid-patch/aliases/`
+   - On macOS, automatically re-signs the binary with `codesign`
+3. **Direct Output** (with `-o`):
+   - Saves the patched binary directly to the specified directory
    - On macOS, automatically re-signs the binary with `codesign`
 
 ## Available Patches
@@ -78,6 +116,376 @@ Changes `isCustom:!0` (true) to `isCustom:!1` (false) for custom models.
 
 **Note**: Side effects are unknown - test thoroughly before production use.
 
+### `--skip-login`
+
+Replaces all `process.env.FACTORY_API_KEY` references in the binary with a hardcoded fake key `"fk-droid-patch-skip-00000"`.
+
+**Purpose**: Bypass the login/authentication requirement without needing to set the `FACTORY_API_KEY` environment variable.
+
+**How it works**:
+- The original code checks `process.env.FACTORY_API_KEY` to authenticate
+- After patching, the code directly uses the fake key string, bypassing the env check
+- This is a binary-level patch, so it works across all terminal sessions without any environment setup
+
+### `--api-base <url>`
+
+Replaces the Factory API base URL (`https://api.factory.ai`) with a custom URL.
+
+**Purpose**: Redirect API requests to a custom server (e.g., local proxy).
+
+**Limitation**: URL must be 22 characters or less (same length as original URL).
+
+**Examples**:
+```bash
+# Valid URLs (<=22 chars)
+npx droid-patch --api-base "http://127.0.0.1:3000" droid-local
+npx droid-patch --api-base "http://localhost:80" droid-local
+
+# Invalid (too long)
+npx droid-patch --api-base "http://my-long-domain.com:3000" droid  # Error!
+```
+
+### `--websearch`
+
+Enables WebSearch functionality through a local proxy server that intercepts `/api/tools/exa/search` requests.
+
+**Purpose**: Enable WebSearch functionality without Factory.ai authentication.
+
+**Features**:
+- **Multiple search providers** with automatic fallback
+- **Auto-start**: Proxy starts automatically when you run the alias
+- **Auto-shutdown**: Proxy shuts down after 5 minutes of inactivity (configurable)
+- **Process detection**: Stays alive as long as droid is running
+
+**Usage**:
+```bash
+# Create alias with websearch
+npx droid-patch --websearch droid-search
+
+# Just run it - everything is automatic!
+droid-search
+```
+
+---
+
+## WebSearch Configuration Guide
+
+The `--websearch` feature supports multiple search providers. Configure them using environment variables in your shell config (`~/.zshrc`, `~/.bashrc`, etc.).
+
+### Search Provider Priority
+
+The proxy tries providers in this order and uses the first one that succeeds:
+
+| Priority | Provider | Quality | Free Tier | Setup Difficulty |
+|----------|----------|---------|-----------|------------------|
+| 1 | Smithery Exa | Excellent | Free (via Smithery) | Easy |
+| 2 | Google PSE | Very Good | 10,000/day | Medium |
+| 3 | Serper | Very Good | 2,500 free credits | Easy |
+| 4 | Brave Search | Good | 2,000/month | Easy |
+| 5 | SearXNG | Good | Unlimited (self-host) | Hard |
+| 6 | DuckDuckGo | Basic | Unlimited | None |
+
+---
+
+## 1. Smithery Exa (Recommended)
+
+[Smithery Exa](https://smithery.ai/server/exa) provides high-quality semantic search results through the MCP protocol. Smithery acts as a free proxy to the Exa search API.
+
+### Setup Steps
+
+1. **Create a Smithery Account**
+   - Go to [smithery.ai](https://smithery.ai)
+   - Sign up for a free account
+
+2. **Get Your API Key**
+   - Navigate to your account settings
+   - Copy your API key
+
+3. **Get Your Profile ID**
+   - Go to [smithery.ai/server/exa](https://smithery.ai/server/exa)
+   - Your profile ID is shown in the connection URL or settings
+
+4. **Configure Environment Variables**
+   ```bash
+   # Add to ~/.zshrc or ~/.bashrc
+   export SMITHERY_API_KEY="your_api_key_here"
+   export SMITHERY_PROFILE="your_profile_id"
+   ```
+
+### Pricing
+
+- **Free** through Smithery (Smithery proxies the Exa API at no cost)
+- Note: The official Exa API (exa.ai) is paid, but Smithery provides free access
+
+---
+
+## 2. Google Programmable Search Engine (PSE)
+
+Google PSE provides high-quality search results with a generous free tier.
+
+### Setup Steps
+
+#### Step 1: Create a Programmable Search Engine
+
+1. Go to [Google Programmable Search Engine Console](https://cse.google.com/all)
+2. Click **"Add"** to create a new search engine
+3. Configure:
+   - **Sites to search**: Enter `*` to search the entire web
+   - **Name**: Give it a descriptive name (e.g., "Web Search")
+4. Click **"Create"**
+5. Click **"Control Panel"** for your new search engine
+6. Copy the **Search engine ID (cx)** - looks like `017576662512468239146:omuauf_lfve`
+
+#### Step 2: Get an API Key
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Enable the **Custom Search API**:
+   - Go to **"APIs & Services"** > **"Library"**
+   - Search for **"Custom Search API"**
+   - Click **"Enable"**
+4. Create credentials:
+   - Go to **"APIs & Services"** > **"Credentials"**
+   - Click **"Create Credentials"** > **"API Key"**
+   - Copy the API key
+
+#### Step 3: Configure Environment Variables
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export GOOGLE_PSE_API_KEY="AIzaSy..."        # Your API key
+export GOOGLE_PSE_CX="017576662512468239146:omuauf_lfve"  # Your Search engine ID
+```
+
+### Free Tier Limits
+
+- **10,000 queries/day** free
+- Max 10 results per query
+- After limit: $5 per 1,000 queries
+
+---
+
+## 3. Serper
+
+[Serper](https://serper.dev) provides Google search results through an easy-to-use API.
+
+### Setup Steps
+
+1. **Create an Account**
+   - Go to [serper.dev](https://serper.dev)
+   - Sign up for a free account
+
+2. **Get Your API Key**
+   - After signing in, your API key is displayed on the dashboard
+   - Copy the API key
+
+3. **Configure Environment Variable**
+   ```bash
+   # Add to ~/.zshrc or ~/.bashrc
+   export SERPER_API_KEY="your_api_key_here"
+   ```
+
+### Free Tier
+
+- **2,500 free credits** on signup
+- 1 credit = 1 search query
+- Paid plans available for more usage
+
+---
+
+## 4. Brave Search
+
+[Brave Search API](https://brave.com/search/api/) provides privacy-focused search results.
+
+### Setup Steps
+
+1. **Create an Account**
+   - Go to [brave.com/search/api](https://brave.com/search/api/)
+   - Click **"Get Started"**
+
+2. **Subscribe to a Plan**
+   - Choose the **Free** plan (2,000 queries/month)
+   - Or a paid plan for more queries
+
+3. **Get Your API Key**
+   - Go to your API dashboard
+   - Copy your API key
+
+4. **Configure Environment Variable**
+   ```bash
+   # Add to ~/.zshrc or ~/.bashrc
+   export BRAVE_API_KEY="BSA..."
+   ```
+
+### Free Tier
+
+- **2,000 queries/month** free
+- Rate limit: 1 query/second
+- Paid plans start at $5/month for 20,000 queries
+
+---
+
+## 5. SearXNG (Self-Hosted)
+
+[SearXNG](https://github.com/searxng/searxng) is a free, privacy-respecting metasearch engine you can self-host.
+
+### Setup Steps
+
+#### Option A: Use a Public Instance
+
+You can use a public SearXNG instance, but availability and reliability vary.
+
+```bash
+# Example public instance (check if it's available)
+export SEARXNG_URL="https://searx.be"
+```
+
+Find public instances at [searx.space](https://searx.space/)
+
+#### Option B: Self-Host with Docker
+
+1. **Run SearXNG with Docker**
+   ```bash
+   docker run -d \
+     --name searxng \
+     -p 8080:8080 \
+     -e SEARXNG_BASE_URL=http://localhost:8080 \
+     searxng/searxng
+   ```
+
+2. **Configure Environment Variable**
+   ```bash
+   # Add to ~/.zshrc or ~/.bashrc
+   export SEARXNG_URL="http://localhost:8080"
+   ```
+
+### Advantages
+
+- Unlimited searches
+- No API key required
+- Privacy-focused
+- Aggregates results from multiple search engines
+
+### Disadvantages
+
+- Requires self-hosting for reliability
+- Public instances may be slow or unavailable
+
+---
+
+## 6. DuckDuckGo (Default Fallback)
+
+DuckDuckGo is used automatically as the final fallback when no other providers are configured or available.
+
+### Configuration
+
+**No configuration required!** DuckDuckGo works out of the box.
+
+### Limitations
+
+- HTML scraping (less reliable than API)
+- Basic results compared to other providers
+- May be rate-limited with heavy use
+
+---
+
+## Quick Configuration Examples
+
+### Minimal Setup (Free, No API Keys)
+
+Just use DuckDuckGo fallback:
+
+```bash
+npx droid-patch --websearch droid-search
+droid-search  # Works immediately with DuckDuckGo
+```
+
+### Recommended Setup (Best Quality)
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+export SMITHERY_API_KEY="your_smithery_key"
+export SMITHERY_PROFILE="your_profile_id"
+
+# Fallback: Google PSE
+export GOOGLE_PSE_API_KEY="your_google_key"
+export GOOGLE_PSE_CX="your_search_engine_id"
+```
+
+### Budget-Friendly Setup (All Free)
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+
+# Option 1: Google PSE (10,000/day free)
+export GOOGLE_PSE_API_KEY="your_google_key"
+export GOOGLE_PSE_CX="your_search_engine_id"
+
+# Option 2: Serper (2,500 free credits)
+export SERPER_API_KEY="your_serper_key"
+
+# Option 3: Brave (2,000/month free)
+export BRAVE_API_KEY="your_brave_key"
+
+# DuckDuckGo is always available as final fallback
+```
+
+---
+
+## Proxy Management
+
+### Auto-Shutdown
+
+The proxy automatically shuts down after 5 minutes of inactivity to save resources.
+
+```bash
+# Customize timeout (in seconds)
+export DROID_PROXY_IDLE_TIMEOUT=600   # 10 minutes
+export DROID_PROXY_IDLE_TIMEOUT=0     # Disable auto-shutdown
+```
+
+### Check Proxy Status
+
+```bash
+npx droid-patch proxy-status
+```
+
+Output shows:
+- Proxy running status
+- Process ID
+- Droid process detection
+- Idle timeout settings
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot search issues:
+
+```bash
+export DROID_SEARCH_DEBUG=1
+droid-search
+```
+
+---
+
+## Examples
+
+```bash
+# Quick start: create droid with websearch
+npx droid-patch --websearch droid-search
+droid-search  # Just works!
+
+# Full-featured droid
+npx droid-patch --is-custom --skip-login --websearch droid-full
+
+# Create a standalone patched binary in current directory
+npx droid-patch --skip-login -o . my-droid
+./my-droid --version
+
+# Clean up
+npx droid-patch remove droid-search   # remove alias and all related files
+npx droid-patch remove ./my-droid     # remove file
+```
+
 ## License
 
 MIT