sf-agent-framework/docs/04-installation/README.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Installation Guide

## Overview

This comprehensive guide covers all installation methods for the SF-Agent Framework, from quick setup to enterprise deployment.

## Prerequisites

### System Requirements

```yaml
minimum_requirements:
  node: '>=20.0.0'
  npm: '>=9.0.0'
  git: '>=2.30.0'
  disk_space: '500MB'
  memory: '4GB RAM'

recommended_requirements:
  node: '>=20.0.0 LTS'
  npm: '>=10.0.0'
  git: 'latest'
  disk_space: '2GB'
  memory: '8GB RAM'

operating_systems:
  - macOS: '11.0+'
  - windows: '10/11 with WSL2'
  - linux: 'Ubuntu 20.04+, Debian 11+, RHEL 8+'
```

### Salesforce Requirements

```yaml
salesforce_requirements:
  cli: 'sfdx-cli or sf-cli'
  org_types:
    - developer_edition
    - sandbox
    - scratch_org
    - production (with caution)

  api_version: '59.0+'

  optional:
    - devops_center: 'For advanced CI/CD'
    - vscode_extensions: 'Salesforce Extension Pack'
```

## Installation Methods

### Method 1: Quick Install (Recommended)

The fastest way to get started:

```bash
# One-command installation
npx sf-agent-framework install

# This will:
# 1. Download the framework
# 2. Set up project structure
# 3. Configure IDE integration
# 4. Initialize git hooks
# 5. Create initial configuration
```

### Method 2: Global Installation

Install globally for system-wide access:

```bash
# Install globally
npm install -g sf-agent-framework

# Verify installation
sf-agent --version

# Initialize in your project
cd your-salesforce-project
sf-agent install
```

### Method 3: Project Installation

Add as a development dependency:

```bash
# Navigate to your project
cd your-salesforce-project

# Install as dev dependency
npm install --save-dev sf-agent-framework

# Initialize framework
npx sf-agent install
```

### Method 4: Manual Installation

For complete control:

```bash
# Clone the repository
git clone https://github.com/kripaSFDC/sf-agent-framework.git

# Navigate to directory
cd sf-agent-framework

# Install dependencies
npm install

# Link for local development
npm link

# In your project
cd ../your-project
npm link sf-agent-framework
```

## Installation Process Details

### Step 1: Initial Setup

When you run `sf-agent install`, the installer will:

```javascript
// Installation Steps
{
  1: "Check system requirements",
  2: "Detect existing Salesforce project",
  3: "Prompt for configuration options",
  4: "Create directory structure",
  5: "Copy framework files",
  6: "Configure IDE integration",
  7: "Set up git hooks",
  8: "Initialize configuration",
  9: "Run post-install scripts",
  10: "Display success message"
}
```

### Step 2: Interactive Configuration

The installer will prompt for:

```yaml
configuration_prompts:
  project_info:
    - project_name: 'Your Salesforce project name'
    - project_type: 'greenfield | brownfield | package'
    - org_type: 'scratch | sandbox | production'

  ide_selection:
    - primary_ide: 'cursor | claude-code | vscode | idea'
    - additional_ides: ['windsurf', 'cline', 'roo']

  feature_selection:
    - two_phase: 'Enable two-phase development?'
    - web_bundles: 'Generate web bundles?'
    - mcp_protocol: 'Configure MCP?'
    - git_hooks: 'Install git hooks?'

  team_setup:
    - team_size: 'small | medium | large | enterprise'
    - primary_clouds: ['sales', 'service', 'experience']
    - compliance: ['hipaa', 'gdpr', 'sox', 'none']
```

### Step 3: Directory Structure Creation

The installer creates:

```
your-project/
├── .sf-core/                    # Framework core (hidden)
│   ├── agents/                  # Agent definitions
│   ├── workflows/               # Workflow configurations
│   ├── templates/               # Document templates
│   ├── tasks/                   # Automation tasks
│   ├── checklists/              # Quality checklists
│   └── config/                  # Framework configuration
│
├── docs/                        # Documentation
│   ├── requirements/            # Sharded requirements
│   ├── architecture/            # Sharded architecture
│   ├── stories/                 # User stories
│   ├── handoffs/                # Agent handoffs
│   └── workflow-sessions/       # Workflow history
│
├── dist/                        # Build outputs
│   ├── agents/                  # Agent bundles
│   └── teams/                   # Team bundles
│
├── .sf-agent/                   # Local configuration
│   ├── config.yaml              # Project configuration
│   ├── metrics.json             # Usage metrics
│   └── cache/                   # Local cache
│
└── [existing project files]
```

## Configuration Options

### Basic Configuration

```yaml
# .sf-agent/config.yaml
project:
  name: 'my-salesforce-project'
  type: 'brownfield'
  version: '1.0.0'

organization:
  type: 'sandbox'
  api_version: '59.0'
  namespace: 'myapp'

framework:
  version: '4.0.0'
  two_phase: true
  auto_update: true

ide:
  primary: 'cursor'
  additional:
    - 'vscode'
    - 'claude-code'
```

### Advanced Configuration

```yaml
# .sf-agent/config.yaml
advanced:
  context_management:
    planning_limit: 128000
    development_limit: 32000
    compression: true
    caching: true

  workflow:
    interactive: true
    validation_gates: true
    parallel_execution: true
    auto_save: true

  integration:
    git:
      auto_commit: false
      branch_strategy: 'feature'
      pr_template: true

    salesforce:
      api_retry: 3
      bulk_api: true
      metadata_api: true

    mcp:
      enabled: true
      servers:
        - 'salesforce-mcp'
        - 'git-mcp'

  security:
    encryption: true
    audit_logging: true
    pii_detection: true
    credential_storage: 'keychain'

  performance:
    parallel_agents: 4
    cache_ttl: 3600
    batch_size: 100
```

## IDE Integration Setup

### VS Code / Cursor

```json
// .vscode/settings.json
{
  "sf-agent.enabled": true,
  "sf-agent.phase": "planning",
  "sf-agent.contextLimit": 128000,
  "sf-agent.autoComplete": true,
  "sf-agent.showMetrics": true
}
```

### Claude Code (Windsurf)

```json
// .windsurf/config.json
{
  "extensions": {
    "sf-agent": {
      "enabled": true,
      "workspace": ".sf-core",
      "defaultAgent": "sf-developer"
    }
  }
}
```

### IntelliJ IDEA

```xml
<!-- .idea/sf-agent.xml -->
<component name="SFAgentSettings">
  <option name="enabled" value="true" />
  <option name="frameworkPath" value=".sf-core" />
  <option name="phase" value="development" />
</component>
```

## Platform-Specific Installation

### macOS

```bash
# Install prerequisites
brew install node@20 git

# Install framework
npx sf-agent-framework install

# Configure for macOS
sf-agent config set platform macos
```

### Windows (WSL2)

```bash
# In WSL2 terminal
# Install prerequisites
sudo apt update
sudo apt install nodejs npm git

# Install framework
npx sf-agent-framework install

# Configure for WSL
sf-agent config set platform wsl2
```

### Linux

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm git

# RHEL/CentOS
sudo yum install nodejs npm git

# Install framework
npx sf-agent-framework install
```

### Docker

```dockerfile
# Dockerfile
FROM node:20-alpine

WORKDIR /app

# Install framework
RUN npm install -g sf-agent-framework

# Copy project
COPY . .

# Initialize framework
RUN sf-agent install --non-interactive

CMD ["sf-agent", "serve"]
```

## Post-Installation Setup

### 1. Verify Installation

```bash
# Check installation
sf-agent doctor

# Expected output:
✅ Node.js version: 20.0.0
✅ NPM version: 10.0.0
✅ Git version: 2.40.0
✅ Framework version: 4.0.0
✅ Configuration: Valid
✅ Dependencies: Installed
✅ IDE Integration: Configured
```

### 2. Initialize Git Hooks

```bash
# Install git hooks
sf-agent hooks install

# This installs:
# - pre-commit: Code validation
# - commit-msg: Message formatting
# - pre-push: Test execution
```

### 3. Configure Salesforce Connection

```bash
# Authorize org
sfdx auth:web:login -a myorg

# Configure framework
sf-agent config set org.alias myorg
sf-agent config set org.api_version 59.0
```

### 4. Build Initial Bundles

```bash
# Build agent bundles
sf-agent build --agents-only

# Build team bundles
sf-agent build --teams-only

# Verify bundles
ls -la dist/agents/
ls -la dist/teams/
```

## Troubleshooting Installation

### Common Issues

#### Issue 1: Node Version Mismatch

```bash
# Error: Requires Node.js >= 20.0.0

# Solution:
# Install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node 20
nvm install 20
nvm use 20
```

#### Issue 2: Permission Denied

```bash
# Error: EACCES: permission denied

# Solution:
# Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

#### Issue 3: Behind Corporate Proxy

```bash
# Configure npm proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# Configure git proxy
git config --global http.proxy http://proxy.company.com:8080
```

#### Issue 4: Disk Space

```bash
# Clean npm cache
npm cache clean --force

# Remove unused packages
npm prune

# Clean framework cache
sf-agent cache clean
```

## Upgrading

### Upgrade Framework

```bash
# Check current version
sf-agent --version

# Check for updates
sf-agent update --check

# Perform update
sf-agent update

# Or reinstall latest
npx sf-agent-framework@latest install
```

### Migration from v3 to v4

```bash
# Run migration wizard
sf-agent migrate v3-to-v4

# This will:
# 1. Backup existing configuration
# 2. Update directory structure
# 3. Migrate agents to two-phase
# 4. Update workflows
# 5. Verify migration
```

## Uninstallation

### Complete Removal

```bash
# Remove framework files
sf-agent uninstall

# Remove global package
npm uninstall -g sf-agent-framework

# Remove project package
npm uninstall --save-dev sf-agent-framework

# Clean directories (manual)
rm -rf .sf-core
rm -rf .sf-agent
rm -rf dist/agents
rm -rf dist/teams
```

### Partial Removal

```bash
# Keep configuration, remove framework
sf-agent uninstall --keep-config

# Keep artifacts, remove framework
sf-agent uninstall --keep-artifacts
```

## Enterprise Installation

### Multi-User Setup

```bash
# Central installation
sudo npm install -g sf-agent-framework

# User-specific configuration
sf-agent config set --user

# Team configuration
sf-agent config set --team engineering
```

### CI/CD Integration

```yaml
# .github/workflows/sf-agent.yml
name: SF-Agent CI/CD

on: [push, pull_request]

jobs:
  sf-agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '20'

      - name: Install SF-Agent
        run: |
          npm install -g sf-agent-framework
          sf-agent install --non-interactive

      - name: Run Validation
        run: sf-agent validate

      - name: Run Tests
        run: sf-agent test
```

### Docker Deployment

```yaml
# docker-compose.yml
version: '3.8'

services:
  sf-agent:
    build: .
    volumes:
      - ./:/app
      - sf-agent-cache:/app/.sf-agent/cache
    environment:
      - SF_AGENT_ENV=production
      - NODE_ENV=production
    ports:
      - '3000:3000'

volumes:
  sf-agent-cache:
```

## Security Considerations

### Credential Management

```yaml
# Never commit credentials
# Use environment variables
environment:
  SALESFORCE_USERNAME: ${SF_USERNAME}
  SALESFORCE_PASSWORD: ${SF_PASSWORD}
  SALESFORCE_TOKEN: ${SF_TOKEN}
```

### File Permissions

```bash
# Secure framework files
chmod 700 .sf-core
chmod 600 .sf-agent/config.yaml
chmod 600 .sf-agent/credentials
```

## Next Steps

After installation:

1. **Read** [Quick Start Guide](../05-quick-start/README.md)
2. **Explore** [Agent System](../07-agents/README.md)
3. **Try** [Interactive Workflows](../12-interactive-workflows/README.md)
4. **Build** [Web Bundles](../16-web-bundles/README.md)
5. **Learn** [Best Practices](../31-best-practices/README.md)

## Support

### Getting Help

- **Documentation**: [Full Docs](../README.md)
- **Issues**: [GitHub Issues](https://github.com/kripaSFDC/sf-agent-framework/issues)
- **Community**: [Discussions](https://github.com/kripaSFDC/sf-agent-framework/discussions)

### Diagnostic Commands

```bash
# System check
sf-agent doctor

# Configuration validation
sf-agent config validate

# Dependency check
sf-agent deps check

# Version information
sf-agent version --all
```

---

_Last Updated: 2025-08-11_
_Version: 4.0.0_