Smart Deployment

Smart Deployment is a Salesforce CLI plugin that analyzes metadata, builds deployment waves, validates project state, and executes staged deployments with optional AI assistance.

The current codebase supports:

• metadata scanning and dependency graph generation
• wave generation with circular dependency detection
• conservative circular dependency remediation for supported ApexClass cycles
• real CLI flows for start, analyze, validate, status, resume, and config
• AI-assisted dependency inference, priority weighting, and validation
• multiple LLM providers through a shared provider abstraction

Current Status

This repository is in active development, but the command surface is now usable as a first working version.

What is working today:

• sf smart-deployment analyze
• sf smart-deployment start
• sf smart-deployment validate
• sf smart-deployment status
• sf smart-deployment resume
• sf smart-deployment config
• sf smart-deployment ci-publish
• JSON and HTML analysis reports
• repo-level AI configuration via .smart-deployment.json

What is still partial:

• full live deployment validation against real Salesforce orgs across all flows
• broader automatic circular dependency remediation beyond simple supported cases
• richer deployment resume/polling semantics against remote deployment backends
• broader provider ecosystem beyond the currently implemented adapters

Installation

sf plugins install @jterrats/smart-deployment

For local development:

yarn install
yarn build
sf plugins link .

Quick Start

Analyze a project:

sf smart-deployment analyze --source-path force-app

Generate a saved plan and JSON report:

sf smart-deployment analyze \
  --source-path force-app \
  --use-ai \
  --save-plan \
  --output analysis.json \
  --format json

Run a dry deployment:

sf smart-deployment start \
  --source-path force-app \
  --dry-run

Run with AI and allow conservative cycle remediation:

sf smart-deployment start \
  --source-path force-app \
  --target-org myorg \
  --use-ai \
  --allow-cycle-remediation

Validate the local wave plan:

sf smart-deployment validate \
  --source-path force-app \
  --use-ai

When to use each:

• use validate for local wave plan readiness and risk checks
• use start --dry-run to rehearse the real deployment command flow without executing the deploy

Show persisted deployment state:

sf smart-deployment status --source-path force-app

Resume a failed deployment from local state:

sf smart-deployment resume \
  --source-path force-app \
  --retry-strategy standard

Configure the default AI provider for a repo:

sf smart-deployment config \
  --source-path . \
  --set-llm-provider openai \
  --set-llm-model gpt-4o-mini

Build a coordinated CI publish plan for metadata, Agentforce authoring bundles, LWR publish, and optional activation:

sf smart-deployment ci-publish \
  --source-path force-app \
  --target-org release \
  --since origin/main \
  --dry-run

When executing deploy phases, Smart Deployment respects .forceignore by building from a temporary sanitized Salesforce project. Ignored files stay in the working tree but are not visible to package generation or sf project deploy start. When --target-org is provided, the coordinated publish flow also passes the org through to Salesforce CLI commands and checks AI evaluation subjects against source metadata or the target org before deploy.

Commands

See:

• CLI reference
• AI configuration
• Known limitations
• Release candidate checklist
• Release workflow
• Documentation index

AI Providers

The AI layer is no longer Agentforce-only.

Current provider model:

• shared provider abstraction in src/ai/llm-provider.ts
• provider factory in src/ai/llm-provider-factory.ts
• concrete adapters currently implemented for:
  • agentforce
  • openai

AI is optional. When unavailable, supported flows fall back to deterministic heuristics where possible.

Repo Configuration

Repo-scoped configuration is stored in:

.smart-deployment.json

Example:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "timeout": 30000
  },
  "priorities": {
    "ApexClass:CriticalService": 100
  }
}

Deployment runtime state is stored separately under .smart-deployment/ and should not be committed.

Testing

Main commands:

yarn test
yarn test:compile
yarn test:only
yarn lint

The suite currently includes unit, integration-style, and NUT coverage for the main CLI flows.

Documentation Policy

The repository contains both active documentation and historical design/planning material.

• active docs live in docs/
• archived historical docs live in docs/archive/

If a document describes flags or workflows that do not exist in the current command layer, treat the archived version as historical only.