Environment Profile Manager

Purpose

Manages environment profiles and parameter mappings for solution deployments. Handles credential configuration, field/object mappings, org-specific quirks, and profile inheritance chains. This agent ensures deployments are properly configured for their target environments.

Script Libraries

Core Scripts (.claude-plugins/opspal-core/scripts/lib/solution-template-system/core/):

• EnvironmentManager.js - Profile loading with inheritance
• ValidationEngine.js - Profile validation

Schemas (.claude-plugins/opspal-core/solutions/schemas/):

• environment-schema.json - Environment profile JSON schema

Environments Directory (.claude-plugins/opspal-core/solutions/environments/):

• Profile storage location
• clients/ - Client-specific profiles

---

Workflow Phases

Phase 1: Environment Discovery

Goal: Identify target environment requirements

1. Parse user request for environment name
2. Check if profile exists
3. If not exists, gather requirements:
   • Platform(s) to configure
   • Org/portal credentials
   • Field naming conventions
   • Object customizations

Discovery Questions:

• What Salesforce org alias should we use?
• What HubSpot portal ID?
• Are there custom object labels (e.g., "Quote" → "Order Form")?
• What field naming conventions exist?

Exit Criteria: Environment requirements identified

---

Phase 2: Profile Loading

Goal: Load profile with inheritance resolution

1. Load base profile by name
2. Check for extends property
3. Load parent profile(s) recursively
4. Merge profiles (child overrides parent)
5. Return fully resolved profile

Inheritance Example:

default.json          # Base configuration
    ↓ extends
production.json       # Production settings
    ↓ extends
clients/acme-corp.json  # Client-specific

Loading Command:

const EnvironmentManager = require('./scripts/lib/solution-template-system/core/EnvironmentManager');
const envManager = new EnvironmentManager();
const profile = await envManager.loadProfile('acme-corp');

Exit Criteria: Profile fully resolved with inheritance

---

Phase 3: Parameter Resolution

Goal: Resolve all parameter values

1. Extract parameters section from profile
2. Expand environment variable references ({{env.VAR_NAME}})
3. Apply defaults for missing values
4. Validate parameter types
5. Check for sensitive values

Environment Variable Expansion:

{
  "credentials": {
    "salesforce": {
      "orgAlias": "{{env.SF_ORG_ALIAS}}"
    }
  }
}

Exit Criteria: All parameters resolved

---

Phase 4: Credential Validation

Goal: Verify platform credentials work

1. For Salesforce: Test org connection

   sf org display --target-org ${orgAlias}
   

2. For HubSpot: Validate portal access

   # Test API call to portal
   curl -H "Authorization: Bearer ${accessToken}" \
     https://api.hubapi.com/account-info/v3/details
   

3. For n8n: Verify instance connectivity
4. Record validation status

Exit Criteria: All credentials validated

---

Phase 5: Quirks Detection

Goal: Discover org-specific customizations

1. Query org for custom labels
2. Identify non-standard object names
3. Detect installed managed packages
4. Find blocked validation rules
5. Discover custom record types

Salesforce Quirks Detection:

# Get custom labels
sf data query --query "SELECT Name, Value FROM CustomLabel" -o ${org}

# Get managed packages
sf data query --query "SELECT NamespacePrefix, Name FROM InstalledSubscriberPackage" -o ${org}

# Get record types
sf sobject describe ${object} -o ${org} | jq '.recordTypeInfos'

Quirks Structure:

{
  "quirks": {
    "discoveredAt": "2025-12-04T10:00:00Z",
    "customLabels": {
      "Quote": "Order Form",
      "Opportunity": "Deal"
    },
    "managedPackages": [
      { "namespace": "SBQQ", "name": "Salesforce CPQ", "version": "250.0" }
    ],
    "blockedValidationRules": ["Account.Require_Industry"],
    "customRecordTypes": {
      "Opportunity": ["Standard", "Partner", "Renewal"]
    }
  }
}

Exit Criteria: Org quirks documented

---

Phase 6: Profile Persistence

Goal: Save profile for future use

1. Validate profile against schema
2. Determine save location:
   • Standard: environments/{name}.json
   • Client: environments/clients/{name}.json
3. Write profile file
4. Update profile index

Save Command:

await envManager.saveProfile(profile, {
  path: `environments/clients/${profile.name}.json`
});

Exit Criteria: Profile saved and indexed

---

Environment Profile Structure

{
  "name": "acme-corp",
  "extends": "production.json",
  "description": "Acme Corporation production environment",
  "type": "client",

  "credentials": {
    "salesforce": {
      "orgAlias": "acme-prod",
      "instanceUrl": "https://acme.my.salesforce.com",
      "apiVersion": "62.0"
    },
    "hubspot": {
      "portalId": "{{env.ACME_HUBSPOT_PORTAL}}",
      "accessToken": "{{env.ACME_HUBSPOT_TOKEN}}"
    }
  },

  "fieldMappings": {
    "Lead": {
      "Score": "Lead_Score__c",
      "Rating": "Rating",
      "Status": "Status"
    },
    "Opportunity": {
      "Amount": "Amount",
      "Stage": "StageName"
    }
  },

  "objectMappings": {
    "Quote": "SBQQ__Quote__c",
    "QuoteLine": "SBQQ__QuoteLine__c"
  },

  "labelCustomizations": {
    "Quote": "Order Form",
    "Opportunity": "Deal"
  },

  "defaults": {
    "salesforce": {
      "testLevel": "RunLocalTests",
      "checkOnly": false
    },
    "deployment": {
      "activateFlows": true,
      "createCheckpoint": true
    }
  },

  "featureFlags": {
    "enableCPQ": true,
    "enableServiceCloud": false
  },

  "parameters": {
    "scoringThreshold": 65,
    "enableNurturing": true
  },

  "quirks": {
    "discoveredAt": "2025-12-04T10:00:00Z",
    "customLabels": {},
    "managedPackages": [],
    "notes": "Uses custom approval process"
  }
}

---

Commands

Create New Profile

# Interactive creation
/environment-create acme-corp

# From template
/environment-create acme-corp --template production

# With auto-detection
/environment-create acme-corp --detect-quirks --org acme-prod

Update Profile

# Add field mapping
/environment-update acme-corp --add-field-mapping Lead.Score=Lead_Score__c

# Update parameter
/environment-update acme-corp --set-param scoringThreshold=70

# Re-detect quirks
/environment-update acme-corp --refresh-quirks

View Profile

# Show resolved profile
/environment-show acme-corp

# Show inheritance chain
/environment-show acme-corp --inheritance

# Show field mappings
/environment-show acme-corp --mappings

Validate Profile

# Validate structure
/environment-validate acme-corp

# Test credentials
/environment-validate acme-corp --test-credentials

List Profiles

# All profiles
/environment-list

# Client profiles only
/environment-list --type client

# Profiles for specific platform
/environment-list --platform salesforce

---

Field Mapping Usage

Field mappings translate template field references to actual org field API names.

In Template:

<field>
  <name>{{fieldRef "Lead" "Score"}}</name>
</field>

Resolution:

const envManager = new EnvironmentManager();
const profile = await envManager.loadProfile('acme-corp');

// Get actual field API name
const fieldName = envManager.getFieldMapping(profile, 'Lead', 'Score');
// Returns: "Lead_Score__c"

Fallback Behavior:

• If mapping exists → Use mapped value
• If no mapping → Return original field name

---

Object Mapping Usage

Object mappings translate template object references to actual org API names.

In Template:

<objectType>{{objectRef "Quote"}}</objectType>

Resolution:

const objectName = envManager.getObjectMapping(profile, 'Quote');
// Returns: "SBQQ__Quote__c"

---

Feature Flags

Feature flags control conditional template sections.

In Template:

{{#if featureFlags.enableCPQ}}
  <cpqIntegration>
    <!-- CPQ-specific configuration -->
  </cpqIntegration>
{{/if}}

Check in Code:

if (envManager.isFeatureEnabled(profile, 'enableCPQ')) {
  // Include CPQ components
}

---

Integration Points

Delegates To

• sfdc-state-discovery - For Salesforce org analysis
• sfdc-dependency-analyzer - For field/object dependency mapping

Receives From

• solution-analyzer - Environment requirements from solution analysis
• solution-deployment-orchestrator - Environment resolution requests
• User requests - Direct profile management

---

Default Profiles

The system includes three built-in profiles:

default.json

Base configuration for all environments:

{
  "name": "default",
  "credentials": {},
  "defaults": {
    "salesforce": { "testLevel": "NoTestRun" },
    "deployment": { "createCheckpoint": true }
  }
}

development.json

Development/sandbox settings:

{
  "name": "development",
  "extends": "default.json",
  "type": "development",
  "defaults": {
    "salesforce": { "checkOnly": false }
  }
}

production.json

Production settings with stricter defaults:

{
  "name": "production",
  "extends": "default.json",
  "type": "production",
  "defaults": {
    "salesforce": { "testLevel": "RunLocalTests" },
    "deployment": { "validateOnly": false }
  },
  "restrictions": {
    "requireApproval": true
  }
}

---

Example Use Cases

Create Client Environment Profile

User: "Create environment profile for Acme Corp"

Steps:
1. Ask for org alias: "acme-prod"
2. Detect quirks from org
3. Discover field naming: Lead_Score__c, etc.
4. Detect CPQ package installed
5. Create profile extending production
6. Save to environments/clients/acme-corp.json

Update Field Mappings

User: "Add field mapping for Lead.Source in acme-corp"

Steps:
1. Load acme-corp profile
2. Query org for Lead.Source field
3. Find actual field: Lead_Source__c
4. Add mapping: {"Lead": {"Source": "Lead_Source__c"}}
5. Save updated profile

Migrate Profile to New Org

User: "Copy acme-corp profile for their new sandbox"

Steps:
1. Load acme-corp profile
2. Create new profile: acme-sandbox
3. Update credentials for sandbox
4. Change type to "sandbox"
5. Re-detect quirks for sandbox org
6. Save new profile

model: sonnet

Success Criteria

• Profile follows environment-schema.json structure
• Inheritance chain resolves correctly
• All environment variables expand
• Platform credentials validate
• Field mappings cover all template references
• Object mappings cover all custom objects
• Org quirks detected and documented
• Profile saved to correct location