Preflight checks for Salesforce changes: know what a change will set off — before it ships.

AI coding agents and Headless 360 make Salesforce changes cheap to produce, but verifying them
is still slow and manual. sf-preflight reads your SFDX project and a git diff, follows the
change through the org's order of execution — flows, triggers, validation rules, roll-ups,
permissions — and reports the blast radius, the risks and the tests that matter.

It is open source, runs offline on your source code, and needs no org credentials.

Status: early (0.x). The CLI, MCP server, GitHub Action, test generation, Agentforce
action verification, the quality gate and evidence packs work today; org context is in beta.
See the roadmap. Feedback and contributions are very welcome.

Website: https://visparashar.github.io/sf-preflight/

What it finds

Every run also produces a suggested test plan: bulk, recursion, validation-collision,
idempotency, boundary and permission-negative tests for exactly what the change touches — and
preflight tests generates the Apex for them.

Quick start

Requires Node.js 22.13 or newer. Run it from the root of an SFDX project:

npx sf-preflight analyze --base origin/main

or install the preflight command globally:

npm install -g sf-preflight
preflight analyze --base origin/main

To run from source instead, see CONTRIBUTING.md.

Usage

# Everything changed since origin/main (committed and uncommitted)
preflight analyze --project path/to/sfdx-project --base origin/main

# Compare two refs
preflight analyze --base origin/main --head HEAD

# Specific files
preflight analyze --files force-app/main/default/objects/Opportunity/fields/Contract_Signed_Date__c.field-meta.xml

# JSON for machines; exit code 2 when risk is high
preflight analyze --base origin/main --format json --out preflight.json --fail-on high

# Quality gate from .preflight.json, plus JUnit for CI and the evidence pack
preflight analyze --base origin/main --gate --junit-out preflight.xml --evidence-out evidence.json

# What runs, in order, when an object is saved?
preflight explain Opportunity --event update

# What can an Agentforce agent do, and what do its actions save?
preflight agents Sales_Agent

# Run the Testing Center tests that cover the change (after deploying it to a sandbox)
preflight agent-tests --base origin/main --org my-sandbox

# Which recent change broke production? And a partial rollback of just that part
preflight incidents --org prod --since 24h
preflight rollback 9c607ea --component ValidationRule:Opportunity.Require_Close_Reason

Example

A one-field change in the bundled sample org:

Opportunity (update)   [changed: Opportunity.Contract_Signed_Date__c]
├─ flow Opportunity_Closed_Won_Followup → Opportunity (update)  ⟲ cycle
├─ flow Opportunity_Closed_Won_Followup → Task (insert)
└─ roll-up Account.Total_Won_Amount__c → Account (update)
   └─ flow Account_Sync_Tier_To_Contacts → Contact (update)
      └─ trigger ContactTrigger → Account (update)  ⟲ cycle

The full Markdown report adds a findings table, the order of execution for each impacted
object, references to the changed field and a test checklist — ready to paste into a PR.

Generate tests

preflight tests --base origin/main

Writes Apex tests for exactly what the change touches to preflight-tests/: bulk saves of 200
records, recursion along automation cycles, flows that must not apply twice, and invocable
actions that must not swallow validation errors. Test data comes from a schema-aware data
factory, with values chosen to meet your flows' entry criteria and pass your validation rules.
Add --validate --org my-sandbox to run them right away: preflight deploys your project and the
tests check-only (Salesforce compiles and runs everything, then rolls it back) and reports each
test's result.

preflight tests --base origin/main --validate --org my-sandbox

See docs/TESTS.md for what is generated and how to read a failure.

Agentforce agents

preflight agents Sales_Agent

Preflight reads agents from source, both Agent Builder metadata and Agent Script (.agent
files), and follows each action to the Apex class or flow it calls and the records that saves.
Every analysis then reports the agent actions a change reaches, whether Testing Center tests
cover them, and the access their runtime user needs. With --org, it checks that user's real
permissions, and preflight agent-tests runs the Testing Center tests that cover the change. See
docs/AGENTS.md.

Quality gate and evidence

{ "gate": { "failOn": "high", "aiAssistedApprovals": 1, "requireAgentTests": true } }

A .preflight.json sets rule severities, ignores and the quality gate: no findings at or
above a severity, approvals for AI-assisted changes, Testing Center coverage for affected agent
actions, passing generated tests. preflight analyze --gate exits with code 2 when it fails.
Every run can also write an evidence pack: what changed (with file digests), who or what
wrote it, findings, tests, approvals and the gate decision, with a tamper-evident digest, ready
for change records and audits.

See docs/CONFIG.md, docs/EVIDENCE.md, and
docs/PIPELINES.md for DevOps Center, GitLab, Azure DevOps, Jenkins and
Bitbucket (JUnit output included).

After it ships: production errors and partial rollback

preflight incidents --org prod

Preflight reads recent failed flow interviews, unhandled Apex exceptions, failed async jobs and
Agentforce action errors from the org (read-only), and traces each one back to the merged change
most likely to have caused it, with the evidence: the change touched the failing component, the
error is the message of a rule it added, the failing flow is in its blast radius, and the errors
started right after it was deployed. preflight rollback then plans a partial rollback of just
those components (restore, or deactivate what the change added) that stays consistent and ships
as a pull request. Messages are reduced to metadata, never record data. See
docs/INCIDENTS.md.

On pull requests (GitHub Action)

permissions:
  contents: read
  pull-requests: write

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 0
  - uses: visparashar/sf-preflight@v0
    with:
      fail-on: high

The action comments the report on the PR (and keeps that comment updated), writes it to the job
summary, evaluates the quality gate with the PR's approvals, uploads the evidence pack (optionally
signed with a GitHub artifact attestation), and can upload findings to code scanning as SARIF.
See docs/GITHUB_ACTION.md.

From AI coding agents (any model)

npx -y sf-preflight skill install   # the agent skill, in .agents/skills and .claude/skills

Coding agents get two things. The agent skill (open Agent Skills
format, read by Codex, GitHub Copilot, Cursor, Gemini CLI, Claude Code and others) tells them
when to check a change and what to do with the findings. The MCP server (preflight mcp,
read-only) gives them the tools: analyze_change, explain_save_order,
find_field_references, explain_agent, generate_tests and plan_rollback. For Claude Code
there's also a plugin that bundles both and checks each metadata edit as it happens:

/plugin marketplace add visparashar/sf-preflight
/plugin install sf-preflight@sf-preflight

Setup for each agent, and an AGENTS.md snippet for agents without skills:
docs/AI_AGENTS.md. MCP tools: docs/MCP.md.

In VS Code

The sf-preflight extension shows findings in the Problems panel as you work,
the blast radius (what runs, in order, on every impacted object) beside your code, and the risk
in the status bar. It re-analyzes when metadata changes, generates tests, explains save order,
and offers the MCP tools to GitHub Copilot and other agents in the editor. It works in VS Code and
editors built on it (Cursor, Salesforce Code Builder).

With org context (beta)

preflight analyze --base origin/main --org my-sandbox

Your SFDX source isn't the whole truth: orgs collect automation that never made it into the
repo. With --org, preflight asks the org (read-only, through your existing sf CLI login)
for record volumes of the impacted objects, active flows, triggers and validation rules that
exist only in the org, how many users hold the permission sets you changed, and installed
packages. The report contains only counts and metadata names. See
docs/ORG_CONTEXT.md.

AI-assisted changes

When analyzing a git range, preflight reads commit trailers and tool markers (Claude, Copilot,
Cursor, Codex, Gemini, Devin and others) and reports how many commits were AI-assisted, so
reviewers know where to look harder. The analysis itself is identical for human and AI changes.

As a library

import { run, toMarkdown } from "sf-preflight";

const result = run({ projectDir: ".", base: "origin/main" });
console.log(result.summary.risk, result.findings.length);
console.log(toMarkdown(result));

How it works

SFDX source ─► parsers ─► org model ─► change mapper ─► order of execution ─► cascade ─► findings ─► Markdown / JSON / SARIF
                                                                                               └─► generated Apex tests

See docs/ARCHITECTURE.md for details and known limitations, and
docs/RULES.md for every rule. In short:
Process Builder, legacy workflow, duplicate and assignment rules are not modelled yet, and the
Apex call graph doesn't follow interfaces or dynamic dispatch.

Contributing and community

Contributions are welcome — especially reports of wrong or missing findings with a small,
anonymised metadata snippet. Read CONTRIBUTING.md to get started, and please
follow our Code of Conduct.

• Questions and help: SUPPORT.md
• Security issues: report privately, see SECURITY.md
• How the project is run: GOVERNANCE.md and MAINTAINERS.md
• What's next: roadmap and changelog

License

Apache License 2.0. See NOTICE for attribution.

Salesforce, Agentforce and related marks are trademarks of Salesforce, Inc. This project is
independent and not affiliated with or endorsed by Salesforce.