sf-agent-framework/sf-core/data/dynamic-configuration-guide.md

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

# Dynamic Configuration Guide for SF-Agent Framework

## Overview

This guide explains how the SF-Agent Framework dynamically reads and uses configuration from your Salesforce project, eliminating the need for hardcoded values.

## Configuration Sources

### 1. Primary: sfdx-project.json

The framework prioritizes reading configuration from your project's `sfdx-project.json`:

```json
{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "sourceApiVersion": "63.0",
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com"
}
```

### 2. Environment Variables (Override)

Environment variables can override project settings:

```bash
export SF_API_VERSION=63.0      # Override API version
export SF_LOGIN_URL=https://test.salesforce.com  # Override login URL
export SF_NAMESPACE=myapp        # Override namespace
```

### 3. Runtime Detection

The framework automatically detects:

- Current system date/time
- Project structure
- Available Salesforce features
- Org configuration

## Key Configuration Items

### API Version

**Dynamic Reading:**

```javascript
// Automatically read from sfdx-project.json
const fs = require('fs');
const projectConfig = JSON.parse(fs.readFileSync('sfdx-project.json', 'utf8'));
const apiVersion = projectConfig.sourceApiVersion || '63.0';
```

**Latest Versions:**

- Winter '25: 63.0 (Current Stable)
- Spring '25: 64.0 (Preview)
- Summer '25: 65.0 (Future)

### Package Directories

**Dynamic Detection:**

```javascript
// Read package directories from project
const packageDirs = projectConfig.packageDirectories;
const defaultDir = packageDirs.find((d) => d.default === true);
const sourcePath = defaultDir?.path || 'force-app';
```

**Standard Structure:**

```
force-app/           # Main application (default)
├── main/
│   └── default/
│       ├── classes/
│       ├── lwc/
│       └── triggers/
force-app-sales/     # Sales module
force-app-service/   # Service module
force-app-integration/ # Integration module
```

### Dates and Timestamps

**Dynamic Generation:**

```javascript
// JavaScript
const currentDate = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
const currentTimestamp = new Date().toISOString(); // Full ISO timestamp

// Bash
CURRENT_DATE=$(date +%Y-%m-%d)
CURRENT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
```

**Template Placeholders:**

- `{{CURRENT_DATE}}` - Replaced with current date
- `{{CURRENT_TIMESTAMP}}` - Replaced with current timestamp
- `{{API_VERSION}}` - Replaced with project API version

## Configuration Validation

### Pre-Flight Checks

Before running any Salesforce operations:

```bash
#!/bin/bash
# Validation script

validate_project() {
  # Check for sfdx-project.json
  if [ ! -f "sfdx-project.json" ]; then
    echo "❌ Error: Not a Salesforce DX project"
    return 1
  fi

  # Validate JSON format
  if ! jq empty sfdx-project.json 2>/dev/null; then
    echo "❌ Error: Invalid sfdx-project.json"
    return 1
  fi

  # Check API version
  API_VERSION=$(jq -r '.sourceApiVersion' sfdx-project.json)
  if [ -z "$API_VERSION" ]; then
    echo "⚠️ Warning: No API version specified, using 63.0"
    API_VERSION="63.0"
  fi

  echo "✅ Valid project with API version: $API_VERSION"
  return 0
}
```

### Configuration Priority

1. Command-line arguments (highest priority)
2. Environment variables
3. sfdx-project.json
4. Framework defaults (lowest priority)

## Agent Configuration

### Agent Initialization

All agents now read configuration dynamically:

```yaml
# Agent metadata
meta:
  version: '{{FRAMEWORK_VERSION}}'
  last_updated: '{{CURRENT_TIMESTAMP}}' # Dynamic timestamp
  api_version: '{{PROJECT_API_VERSION}}' # From sfdx-project.json
```

### Agent Commands

Agents use dynamic configuration in commands:

```bash
# Deploy with dynamic settings
sf project deploy start \
  --source-dir "$(get_package_dir)" \
  --api-version "$(get_api_version)" \
  --target-org "$TARGET_ORG"
```

## MCP Server Configuration

### Dynamic API Version

MCP servers read API version at startup:

```javascript
class SalesforceMCPServer {
  getApiVersionFromProject() {
    try {
      const projectPath = path.join(process.cwd(), 'sfdx-project.json');
      if (fs.existsSync(projectPath)) {
        const config = JSON.parse(fs.readFileSync(projectPath, 'utf8'));
        return config.sourceApiVersion || '63.0';
      }
    } catch (error) {
      console.warn('Using default API version');
    }
    return '63.0';
  }
}
```

## Configuration Files

### Required Files

1. **sfdx-project.json** (Required)
   - Defines project structure
   - Sets API version
   - Configures packages

2. **config/project-scratch-def.json** (For scratch orgs)
   - Org shape definition
   - Features to enable
   - Settings and preferences

### Optional Files

1. **.sf/config.json** (Local settings)
2. **.forceignore** (Files to ignore)
3. **sfdx-config.json** (Legacy, if exists)

## Best Practices

### 1. Never Hardcode

❌ **Bad:**

```javascript
const API_VERSION = '59.0';
const PACKAGE_DIR = 'src-core';
```

✅ **Good:**

```javascript
const API_VERSION = getApiVersionFromProject();
const PACKAGE_DIR = getPackageDirectory();
```

### 2. Always Validate

✅ **Always check before using:**

```bash
if [ -f "sfdx-project.json" ]; then
  # Safe to read configuration
else
  echo "Not in a Salesforce project"
  exit 1
fi
```

### 3. Provide Fallbacks

✅ **Have sensible defaults:**

```javascript
const apiVersion = config?.sourceApiVersion || '63.0';
const packageDir = config?.packageDirectories?.[0]?.path || 'force-app';
```

### 4. Log Configuration

✅ **Show what's being used:**

```bash
echo "Using configuration:"
echo "  API Version: $API_VERSION"
echo "  Package Dir: $PACKAGE_DIR"
echo "  Target Org: $TARGET_ORG"
```

## Troubleshooting

### Common Issues

**Issue: "Not a Salesforce DX project"**

- Solution: Ensure sfdx-project.json exists in project root
- Run: `sf project generate` to create one

**Issue: "Invalid API version"**

- Solution: Update sourceApiVersion in sfdx-project.json
- Check latest: https://developer.salesforce.com/docs/

**Issue: "Package directory not found"**

- Solution: Verify packageDirectories in sfdx-project.json
- Ensure directories exist on filesystem

**Issue: "Configuration not loading"**

- Check file permissions
- Validate JSON syntax: `jq empty sfdx-project.json`
- Review environment variables: `env | grep SF_`

## Migration from Static Configuration

### Old Approach (Deprecated)

```javascript
// Hardcoded values
const config = {
  apiVersion: '59.0',
  packageDir: 'src-core',
  loginUrl: 'https://login.salesforce.com',
};
```

### New Approach (Current)

```javascript
// Dynamic configuration
const config = new SfdxProjectConfig();
const settings = {
  apiVersion: config.getApiVersion(),
  packageDir: config.getDefaultPackageDirectory(),
  loginUrl: config.getLoginUrl(),
};
```

## Monitoring Configuration

### Health Check Script

```bash
#!/bin/bash
# config-health-check.sh

echo "Configuration Health Check"
echo "========================="

# Check project file
[ -f "sfdx-project.json" ] && echo "✅ Project file exists" || echo "❌ Project file missing"

# Check API version
API_VERSION=$(jq -r '.sourceApiVersion' sfdx-project.json 2>/dev/null)
[ -n "$API_VERSION" ] && echo "✅ API Version: $API_VERSION" || echo "❌ No API version"

# Check package directories
PACKAGE_COUNT=$(jq '.packageDirectories | length' sfdx-project.json 2>/dev/null)
echo "📦 Package directories: $PACKAGE_COUNT"

# Check environment
[ -n "$SF_API_VERSION" ] && echo "⚙️ ENV Override: $SF_API_VERSION"

# Check CLI version
sf version && echo "✅ SF CLI installed" || echo "❌ SF CLI not found"
```

## Future Enhancements

### Planned Features

1. **Auto-detection of latest API version**
2. **Configuration caching for performance**
3. **Multi-project configuration support**
4. **Configuration inheritance**
5. **Hot-reload of configuration changes**

### Configuration Evolution

The framework will continue to evolve toward:

- Zero configuration for common scenarios
- Smart defaults based on project analysis
- Automatic optimization suggestions
- Configuration validation and linting

## References

- [Salesforce DX Project Configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_config.htm)
- [SF CLI Configuration](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_sf_config.htm)
- [API Version Reference](https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/)

---

**Note:** This guide reflects the current state of the SF-Agent Framework v4.0+ with full dynamic configuration support. All hardcoded values have been replaced with dynamic references that adapt to your project's configuration.