feat: Add --frontend-dev-mode CLI option for enhanced frontend development

[wilfredeveloper]

🚀 Feature: Frontend Development Mode for ADK FastAPI CLI

This PR adds a new --frontend-dev-mode CLI option that significantly enhances the development experience when building frontend applications that connect to ADK agents.

✨ Key Features

• 🔗 Automatic CORS Configuration: Automatically adds CORS origins for common frontend development servers (React, Angular, Vue, Vite)
• 🐛 Enhanced Error Handling: Provides detailed error responses with stack traces and request information for better debugging
• 📊 Development Headers: Adds helpful headers like X-Frontend-Dev-Mode and X-Server-Time to all responses
• ℹ️ Dev Info Endpoint: New /dev-info endpoint provides configuration information to frontend developers

🎯 Supported Frontend Frameworks

Automatically configures CORS for:

• React/Next.js (localhost:3000, 3001)
• Angular (localhost:4200)
• Vite (localhost:5173)
• Vue CLI (localhost:8080)
• Plus 127.0.0.1 variants

📋 Usage Examples

# Enable frontend dev mode with web UI
adk web --frontend-dev-mode /path/to/agents

# Enable frontend dev mode with API server only
adk api_server --frontend-dev-mode --port 8000 /path/to/agents

# Combine with custom CORS origins
adk web --frontend-dev-mode --allow_origins https://myapp.com /path/to/agents

🔧 Implementation Details

Files Modified:

• src/google/adk/cli/cli_tools_click.py - Added CLI option and parameter passing
• src/google/adk/cli/fast_api.py - Implemented core functionality and middleware
• tests/unittests/cli/test_fast_api.py - Added comprehensive tests
• tests/unittests/conftest.py - Fixed import issue for testing

New Files:

• FRONTEND_DEV_MODE_FEATURE.md - Comprehensive documentation

✅ Benefits for Frontend Developers

1. Zero Configuration CORS - No need to manually configure CORS for common dev servers
2. Better Debugging - Detailed error responses help identify issues quickly
3. Development Visibility - Headers and endpoints provide insight into server state
4. Faster Iteration - Automatic reload and dev-friendly settings speed up development

🔒 Security Considerations

• Development Only - Feature is disabled by default and requires explicit opt-in
• Backwards Compatible - Existing deployments are unaffected
• Production Safe - Should only be used in development environments

🧪 Testing

• Added comprehensive unit tests for all new functionality
• Tests cover both enabled and disabled states of frontend dev mode
• Verified CORS origin configuration and header injection
• Tested new /dev-info endpoint

📚 Documentation

Includes detailed documentation covering:

• Feature overview and benefits
• Usage examples and CLI syntax
• Implementation details
• Security considerations
• Frontend integration examples
• Troubleshooting guide

📝 Technical Implementation

CLI Option Addition

@click.option(
    "--frontend-dev-mode",
    is_flag=True,
    show_default=True,
    default=False,
    help=(
        "Optional. Enable frontend development mode. Automatically configures "
        "CORS for common frontend dev ports (3000, 3001, 4200, 5173, 8080), "
        "enables detailed error responses, and sets up proxy-friendly headers."
    ),
)

Automatic CORS Configuration

if frontend_dev_mode:
    dev_origins = [
        "http://localhost:3000",    # React, Next.js default
        "http://localhost:3001",    # React alternative
        "http://localhost:4200",    # Angular default
        "http://localhost:5173",    # Vite default
        "http://localhost:8080",    # Vue CLI default
        # Plus 127.0.0.1 variants
    ]
    cors_origins.extend(dev_origins)

Enhanced Error Handling

@app.middleware("http")
async def frontend_dev_middleware(request: Request, call_next):
    try:
        response = await call_next(request)
        # Add development headers
        response.headers["X-Frontend-Dev-Mode"] = "true"
        response.headers["X-Server-Time"] = str(int(time.time()))
        return response
    except Exception as e:
        # Provide detailed error information in dev mode
        error_detail = {
            "error": str(e),
            "type": type(e).__name__,
            "traceback": traceback.format_exc(),
            "request_info": {...}
        }
        return JSONResponse(status_code=500, content=error_detail)

---

This enhancement makes ADK FastAPI servers much more developer-friendly when building frontend applications, reducing configuration overhead and improving the debugging experience during development.

🔍 Related Issues

This addresses common pain points developers face when:

• Setting up CORS for frontend development
• Debugging API connection issues
• Understanding server configuration
• Iterating quickly during development

🚀 Future Enhancements

Potential future improvements could include:

• WebSocket connection debugging
• Request/response logging in dev mode
• Hot-reload notifications to frontend
• Development metrics dashboard

---

Pull Request opened by Augment Code with guidance from the PR author

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.