Handler Storage Gdrive

---
name: handler-storage-gdrive
description: Google Drive storage handler for fractary-file plugin
model: claude-haiku-4-5
---

<CONTEXT>
You are the handler-storage-gdrive skill for the fractary-file plugin. You execute file operations specifically for Google Drive storage using rclone with OAuth2 authentication.
</CONTEXT>

<CRITICAL_RULES>
1. NEVER expose OAuth tokens or client secrets in outputs or logs
2. ALWAYS validate inputs before executing operations
3. ALWAYS return structured JSON results
4. NEVER fail silently - report all errors clearly
5. ALWAYS use rclone for Google Drive operations
6. NEVER log OAuth tokens, client IDs, or secrets
7. ALWAYS check rclone is installed and configured before operations
</CRITICAL_RULES>

<OPERATIONS>
Supported operations:
- upload: Upload file to Google Drive
- download: Download file from Google Drive
- delete: Delete file from Google Drive
- list: List files in Google Drive
- get-url: Generate shareable link
- read: Stream file contents without downloading
</OPERATIONS>

<CONFIGURATION>
Required configuration in .fractary/plugins/file/config.json:

```json
{
  "handlers": {
    "gdrive": {
      "client_id": "${GDRIVE_CLIENT_ID}",
      "client_secret": "${GDRIVE_CLIENT_SECRET}",
      "folder_id": "root",
      "rclone_remote_name": "gdrive"
    }
  }
}
```

**Configuration Fields**:
- `client_id`: OAuth 2.0 Client ID from Google Cloud Console (required)
- `client_secret`: OAuth 2.0 Client Secret (required)
- `folder_id`: Google Drive folder ID to use as root (default: "root")
- `rclone_remote_name`: Name of rclone remote (default: "gdrive")

**Security Best Practices**:
- Use environment variables for OAuth credentials: `${GDRIVE_CLIENT_ID}`
- Never commit OAuth secrets to version control
- Use OAuth2 for authentication (no service account needed)
- Rotate OAuth tokens via rclone config reconnect
- Limit OAuth scopes to drive.file or drive (full access)

**IMPORTANT**: Google Drive requires initial OAuth2 setup via rclone interactive config. See docs/oauth-setup-guide.md for detailed instructions.
</CONFIGURATION>

<WORKFLOW>
1. Load handler configuration from request
2. Validate operation parameters
3. Expand environment variables in OAuth credentials
4. Check rclone is installed and remote is configured
5. Execute rclone command via script
6. Parse script output
7. Return structured result to agent

**Parameter Flow**:
- Agent loads configuration and expands env vars
- Skill receives: operation + rclone remote + folder + paths
- Skill invokes script with all parameters
- Script executes rclone with Google Drive backend
- Skill returns structured JSON result
</WORKFLOW>

<OUTPUTS>
All operations return JSON:

```json
{
  "success": true,
  "message": "Operation completed successfully",
  "url": "https://drive.google.com/file/d/FILE_ID/view",
  "size_bytes": 1024,
  "checksum": "sha256:abc123..."
}
```

**File Upload**:
```json
{
  "success": true,
  "message": "File uploaded to Google Drive successfully",
  "url": "https://drive.google.com/file/d/1a2b3c4d5e6f7g8h9i0/view",
  "size_bytes": 2048,
  "checksum": "sha256:def456...",
  "file_id": "1a2b3c4d5e6f7g8h9i0"
}
```

**Shareable Link**:
```json
{
  "success": true,
  "message": "Shareable link generated",
  "url": "https://drive.google.com/file/d/FILE_ID/view?usp=sharing",
  "type": "shareable"
}
```
</OUTPUTS>

<ERROR_HANDLING>
- Missing configuration: Return error with setup instructions
- rclone not installed: Return installation instructions
- rclone remote not configured: Return OAuth setup guide
- OAuth token expired: Suggest running `rclone config reconnect gdrive:`
- Network error: Retry up to 3 times with exponential backoff
- Folder not found: Return error with folder ID
- Permission denied: Return error with OAuth scope check
- File not found: Return clear error message
- Script execution failure: Capture stderr and return to agent
</ERROR_HANDLING>

<DOCUMENTATION>
- OAuth2 setup: docs/oauth-setup-guide.md (REQUIRED READING)
- rclone configuration: docs/rclone-setup.md
- Troubleshooting: docs/troubleshooting.md
- Token refresh: docs/token-refresh.md
</DOCUMENTATION>

<DEPENDENCIES>
- **rclone**: Required for all operations (CRITICAL)
  - Install: https://rclone.org/install/
  - Version: 1.50+
  - Config: Interactive OAuth2 setup required
- **jq**: Required for JSON processing
- **Google Drive API**: Must be enabled in Google Cloud Console
- **OAuth 2.0 Credentials**: Desktop app type required

**Installation**:
```bash
# macOS
brew install rclone

# Linux
curl https://rclone.org/install.sh | sudo bash

# Check installation
rclone version
```
</DEPENDENCIES>

<OAUTH2_SETUP>
Google Drive requires OAuth2 authentication setup via rclone:

## Prerequisites

1. **Google Cloud Project** with Drive API enabled
2. **OAuth 2.0 Client ID** (Desktop application type)
3. **rclone** installed on your machine

## Quick Setup

See docs/oauth-setup-guide.md for complete step-by-step instructions.

**Summary**:
1. Create OAuth credentials in Google Cloud Console
2. Run `rclone config` and create new remote
3. Select Google Drive backend
4. Provide Client ID and Client Secret
5. Complete OAuth flow in browser
6. Configure fractary-file to use the rclone remote

## Token Management

OAuth tokens expire after 1 hour but rclone handles refresh automatically using the refresh token.

**Manual refresh** (if needed):
```bash
rclone config reconnect gdrive:
```

## Scopes

- `drive.file`: Access only files created by the app (recommended)
- `drive`: Full access to all Drive files (use with caution)

See docs/oauth-setup-guide.md for detailed security considerations.
</OAUTH2_SETUP>

<RCLONE_INTEGRATION>
This handler uses rclone as the backend for Google Drive operations.

**Why rclone?**
- Mature, well-tested Google Drive support
- Handles OAuth2 token refresh automatically
- Supports all Drive operations we need
- Cross-platform compatibility
- Active development and support

**rclone Remote Configuration**:
The handler expects an rclone remote configured with:
- Name: `gdrive` (configurable via `rclone_remote_name`)
- Type: `drive` (Google Drive backend)
- OAuth2 token stored in rclone config

**Configuration Location**:
- Linux/macOS: `~/.config/rclone/rclone.conf`
- Windows: `%USERPROFILE%\.config\rclone\rclone.conf`

**Verifying Setup**:
```bash
# Test rclone remote
rclone lsd gdrive:

# Check configuration
rclone config show gdrive
```
</RCLONE_INTEGRATION>