@jterrats/smart-deployment 1.2.6 → 1.4.0

package/oclif.manifest.json

@@ -338,14 +338,740 @@
         "config"
       ]
     },
+    "impact": {
+      "aliases": [
+        "smart-deployment:impact"
+      ],
+      "args": {},
+      "description": "Maps git changes to Salesforce metadata components, expands transitive dependents, reports planned deployment waves, and suggests Apex tests for CI decisions.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --base origin/main --head HEAD --json",
+        "<%= config.bin %> smart-deployment impact --working-tree --source-path force-app"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-path": {
+          "description": "Path to the Salesforce source directory used to build the dependency graph and deployment waves.",
+          "name": "source-path",
+          "summary": "Salesforce source path to analyze",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base": {
+          "description": "Git ref at the start of the comparison range. Must be provided with --head.",
+          "name": "base",
+          "summary": "Base git ref for impact analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "head": {
+          "description": "Git ref at the end of the comparison range. Must be provided with --base.",
+          "name": "head",
+          "summary": "Head git ref for impact analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "working-tree": {
+          "description": "Uses git status to include staged, unstaged, and untracked working-tree changes. This is the default when --base and --head are omitted.",
+          "name": "working-tree",
+          "summary": "Analyze current working-tree changes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "max-depth": {
+          "description": "Limits transitive dependent traversal. Omit for unlimited depth.",
+          "name": "max-depth",
+          "summary": "Maximum dependent traversal depth",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "impact",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Analyze deployment impact from git changes",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "impact.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:impact",
+        "impact:smart-deployment"
+      ],
+      "permutations": [
+        "impact"
+      ]
+    },
+    "init": {
+      "aliases": [
+        "smart-deployment:init"
+      ],
+      "args": {},
+      "description": "Detects Salesforce project source settings and writes .smart-deployment.json defaults for cache policy, CI preset behavior, and report locations.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> smart-deployment init --source-path force-app --validation-mode warn-only --non-interactive",
+        "<%= config.bin %> smart-deployment init --force --no-cache-enabled"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-path": {
+          "name": "source-path",
+          "summary": "Path used to detect the Salesforce project and default package directory",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "force": {
+          "char": "f",
+          "name": "force",
+          "summary": "Overwrite an existing .smart-deployment.json file",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "cache-enabled": {
+          "name": "cache-enabled",
+          "summary": "Enable file-hash cache defaults in generated config",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "validation-mode": {
+          "name": "validation-mode",
+          "summary": "Default validation mode for the CI preset",
+          "default": "strict",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "strict",
+            "warn-only",
+            "local-only"
+          ],
+          "type": "option"
+        },
+        "report-dir": {
+          "name": "report-dir",
+          "summary": "Default report directory for CI preset plan artifacts",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "skip-tests": {
+          "name": "skip-tests",
+          "summary": "Default skip-tests setting for CI preset config",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "non-interactive": {
+          "name": "non-interactive",
+          "summary": "Run with deterministic defaults suitable for CI automation",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Initialize Smart Deployment repository config",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "init.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:init",
+        "init:smart-deployment"
+      ],
+      "permutations": [
+        "init"
+      ]
+    },
     "resume": {
       "aliases": [
-        "smart-deployment:resume"
+        "smart-deployment:resume"
+      ],
+      "args": {},
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --source-path force-app",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --retry-strategy quick"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Target Salesforce org alias or username for remote deployment resume",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-path": {
+          "name": "source-path",
+          "summary": "Path to the Salesforce project containing deployment state",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "retry-strategy": {
+          "name": "retry-strategy",
+          "summary": "Retry strategy to use when resuming the deployment",
+          "default": "standard",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "standard",
+            "quick",
+            "validate-only"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "resume",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Resume a failed deployment",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "resume.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:resume",
+        "resume:smart-deployment"
+      ],
+      "permutations": [
+        "resume"
+      ]
+    },
+    "retrieve": {
+      "aliases": [
+        "smart-deployment:retrieve"
+      ],
+      "args": {},
+      "description": "Wraps sf project retrieve start, then restores any changed paths protected by .forceignore. This protects DigitalExperienceBundle, LightningComponentBundle, and AuraDefinitionBundle leaf paths that the Salesforce CLI can write as part of composite retrieves.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --metadata DigitalExperienceBundle:site/PHP_Portal1 --target-org dev",
+        "<%= config.bin %> <%= command.id %> --metadata DigitalExperienceBundle:site/PHP_Portal1 --strict-ignore",
+        "<%= config.bin %> <%= command.id %> --metadata DigitalExperienceBundle:site/PHP_Portal1 --normalize-meta"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "aliases": [
+            "targetusername",
+            "u"
+          ],
+          "char": "o",
+          "deprecateAliases": true,
+          "name": "target-org",
+          "noCacheDefault": true,
+          "summary": "Username or alias of the target org.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-path": {
+          "description": "Defaults to the current working directory when omitted.",
+          "name": "source-path",
+          "summary": "Salesforce project path where retrieve should run",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "metadata": {
+          "char": "m",
+          "description": "Passed through to sf project retrieve start --metadata. Example: DigitalExperienceBundle:site/PHP_Portal1.",
+          "name": "metadata",
+          "summary": "Metadata component(s) to retrieve, comma-separated",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "manifest": {
+          "char": "x",
+          "description": "Passed through to sf project retrieve start --manifest.",
+          "name": "manifest",
+          "summary": "Package manifest to retrieve",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "name": "wait",
+          "summary": "Minutes to wait for Salesforce retrieve completion",
+          "default": 33,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "strict-ignore": {
+          "description": "Protected paths are still restored before the command fails.",
+          "name": "strict-ignore",
+          "summary": "Fail when retrieve touches .forceignore-protected paths",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "normalize-meta": {
+          "description": "Formats JSON with two-space indentation and a trailing newline before forceignore restoration.",
+          "name": "normalize-meta",
+          "summary": "Normalize DigitalExperienceBundle *_meta.json formatting after retrieve",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "retrieve",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Retrieve Salesforce metadata while enforcing .forceignore for bundle sub-paths",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "retrieve.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:retrieve",
+        "retrieve:smart-deployment"
+      ],
+      "permutations": [
+        "retrieve"
+      ]
+    },
+    "start": {
+      "aliases": [
+        "smart-deployment:start"
+      ],
+      "args": {},
+      "description": "Analyzes your Salesforce metadata, generates deployment waves based on dependencies, and executes the deployment sequentially. This command orchestrates the entire smart deployment workflow.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --dry-run",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --validate-only",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --skip-tests",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --destructive",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --rollback-from v1.2.0 --rollback-to v1.2.1"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Target Salesforce org for deployment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dry-run": {
+          "char": "d",
+          "name": "dry-run",
+          "summary": "Preview deployment without executing",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "validate-only": {
+          "char": "v",
+          "name": "validate-only",
+          "summary": "Validate the local wave plan without deploying",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "skip-tests": {
+          "char": "s",
+          "name": "skip-tests",
+          "summary": "Skip running tests during deployment",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "source-path": {
+          "description": "Defaults to the current working directory when omitted",
+          "name": "source-path",
+          "summary": "Path to the Salesforce project to analyze and deploy",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "report-dir": {
+          "description": "Defaults to .smart-deployment/reports/start-dry-run under the scanned project root",
+          "name": "report-dir",
+          "summary": "Directory for dry-run deployment plan reports",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "allow-cycle-remediation": {
+          "description": "Applies temporary reversible source edits for simple cycles only",
+          "name": "allow-cycle-remediation",
+          "summary": "Allow conservative cycle remediation for supported ApexClass cycles",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "use-ai": {
+          "description": "Enables provider-backed analysis for deployment prioritization",
+          "name": "use-ai",
+          "summary": "Use AI for intelligent priority weighting and dependency inference",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "org-type": {
+          "description": "Helps AI provide context-aware recommendations",
+          "name": "org-type",
+          "summary": "Organization type context for AI analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "Production",
+            "Sandbox",
+            "Developer"
+          ],
+          "type": "option"
+        },
+        "industry": {
+          "description": "Provides business context to AI for better prioritization",
+          "name": "industry",
+          "summary": "Industry context for AI analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-commits": {
+          "description": "Limits the deployment plan to metadata changed by these commits plus required dependencies.",
+          "name": "scope-commits",
+          "summary": "Comma-separated commit SHAs or refs to include in the deployment scope",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-manifest": {
+          "description": "Reads commits from { commits: [] } and { stories: [{ commits: [] }] } to scope validation and deployment planning.",
+          "name": "scope-manifest",
+          "summary": "Path to a JSON commit or story scope manifest",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-manifest-output": {
+          "description": "Creates a deterministic JSON contract containing commits, changed files, included metadata, dependency-retained metadata, explicitly included metadata, and ignored metadata.",
+          "name": "scope-manifest-output",
+          "summary": "Write the resolved story scope manifest for CI review",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "destructive": {
+          "description": "Runs the normal analysis path, then executes destructiveChanges manifests in reverse wave order.",
+          "name": "destructive",
+          "summary": "Delete metadata components using destructive wave manifests",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "rollback-from": {
+          "description": "Use with --rollback-to. Modified or deleted metadata is restored from this ref using normal deploy waves.",
+          "name": "rollback-from",
+          "summary": "Git ref or release tag that represents the rollback target state",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "rollback-to": {
+          "description": "Use with --rollback-from. Metadata added between refs is deleted using destructive waves.",
+          "name": "rollback-to",
+          "summary": "Git ref or release tag that represents the release being rolled back",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "start",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Deploy Salesforce metadata intelligently with automatic wave generation",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "start.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:start",
+        "start:smart-deployment"
+      ],
+      "permutations": [
+        "start"
+      ]
+    },
+    "status": {
+      "aliases": [
+        "smart-deployment:status"
+      ],
+      "args": {},
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --source-path force-app",
+        "<%= config.bin %> <%= command.id %> --target-org myorg --source-path force-app"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "summary": "Target Salesforce org alias or username for remote deployment status refresh",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-path": {
+          "name": "source-path",
+          "summary": "Path to the Salesforce project containing deployment state",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "status",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Show deployment status",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "status.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:status",
+        "status:smart-deployment"
+      ],
+      "permutations": [
+        "status"
+      ]
+    },
+    "validate": {
+      "aliases": [
+        "smart-deployment:validate"
+      ],
+      "args": {},
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --source-path force-app",
+        "<%= config.bin %> <%= command.id %> --source-path force-app --use-ai"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "aliases": [
+            "targetusername",
+            "u"
+          ],
+          "char": "o",
+          "deprecateAliases": true,
+          "name": "target-org",
+          "noCacheDefault": true,
+          "summary": "Username or alias of the target org.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "source-path": {
+          "name": "source-path",
+          "summary": "Path to the Salesforce project to validate",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "use-ai": {
+          "name": "use-ai",
+          "summary": "Use configured provider AI validation when available",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "scope-commits": {
+          "name": "scope-commits",
+          "summary": "Comma-separated commit SHAs or refs to include in validation",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-manifest": {
+          "name": "scope-manifest",
+          "summary": "Path to a JSON commit or story scope manifest",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-manifest-output": {
+          "description": "Creates a deterministic JSON contract containing commits, changed files, included metadata, dependency-retained metadata, explicitly included metadata, and ignored metadata.",
+          "name": "scope-manifest-output",
+          "summary": "Write the resolved story scope manifest for CI review",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "validate",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Validate the local wave plan without deploying",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "validate.js"
+      ],
+      "aliasPermutations": [
+        "smart-deployment:validate",
+        "validate:smart-deployment"
+      ],
+      "permutations": [
+        "validate"
+      ]
+    },
+    "ci:preset": {
+      "aliases": [
+        "smart-deployment:ci:preset"
       ],
       "args": {},
+      "description": "Builds a validation-safe deployment plan, writes JSON and HTML report artifacts, emits GitHub Actions output keys, and returns deterministic CI exit codes.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --source-path force-app",
-        "<%= config.bin %> <%= command.id %> --source-path force-app --retry-strategy quick"
+        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org dev --report-dir reports/deployment-plan",
+        "<%= config.bin %> smart-deployment ci preset --validation-mode warn-only --skip-tests"
       ],
       "flags": {
         "json": {
@@ -378,60 +1104,122 @@
           "type": "option"
         },
         "source-path": {
+          "description": "Path to the Salesforce source directory used to build the deployment plan.",
           "name": "source-path",
-          "summary": "Path to the Salesforce project containing deployment state",
+          "summary": "Salesforce source path to analyze",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "retry-strategy": {
-          "name": "retry-strategy",
-          "summary": "Retry strategy to use when resuming the deployment",
-          "default": "standard",
+        "report-dir": {
+          "description": "Defaults to the deployment plan report service location under the analyzed project.",
+          "name": "report-dir",
+          "summary": "Directory where JSON and HTML deployment plan reports are written",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "validation-mode": {
+          "description": "strict exits non-zero for blockers, warn-only reports blockers with exit code 0, and local-only avoids org-dependent validation expectations.",
+          "name": "validation-mode",
+          "summary": "CI exit-code policy for deployment planning blockers",
+          "default": "strict",
           "hasDynamicHelp": false,
           "multiple": false,
           "options": [
-            "standard",
-            "quick",
-            "validate-only"
+            "strict",
+            "warn-only",
+            "local-only"
+          ],
+          "type": "option"
+        },
+        "skip-tests": {
+          "name": "skip-tests",
+          "summary": "Record that Apex tests should be skipped by downstream validation",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "use-ai": {
+          "name": "use-ai",
+          "summary": "Use configured AI providers for dependency inference and wave priority analysis",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "org-type": {
+          "name": "org-type",
+          "summary": "Target org type used by AI wave priority analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "Production",
+            "Sandbox",
+            "Developer"
           ],
           "type": "option"
+        },
+        "industry": {
+          "name": "industry",
+          "summary": "Industry context used by AI wave priority analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-commits": {
+          "description": "Limits CI plan artifacts to metadata changed by these commits plus required dependencies.",
+          "name": "scope-commits",
+          "summary": "Comma-separated commit SHAs or refs to include in the CI deployment scope",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-manifest": {
+          "description": "Reads commits from { commits: [] } and { stories: [{ commits: [] }] } for trunk-based validation.",
+          "name": "scope-manifest",
+          "summary": "Path to a JSON commit or story scope manifest",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "resume",
+      "id": "ci:preset",
       "pluginAlias": "@jterrats/smart-deployment",
       "pluginName": "@jterrats/smart-deployment",
       "pluginType": "core",
       "strict": true,
-      "summary": "Resume a failed deployment",
+      "summary": "Run the CI deployment planning preset",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "resume.js"
+        "ci",
+        "preset.js"
       ],
       "aliasPermutations": [
-        "smart-deployment:resume",
-        "resume:smart-deployment"
+        "smart-deployment:ci:preset",
+        "ci:smart-deployment:preset",
+        "ci:preset:smart-deployment",
+        "smart-deployment:preset:ci",
+        "preset:smart-deployment:ci",
+        "preset:ci:smart-deployment"
       ],
       "permutations": [
-        "resume"
+        "ci:preset",
+        "preset:ci"
       ]
     },
-    "start": {
+    "graph:export": {
       "aliases": [
-        "smart-deployment:start"
+        "smart-deployment:graph:export"
       ],
       "args": {},
-      "description": "Analyzes your Salesforce metadata, generates deployment waves based on dependencies, and executes the deployment sequentially. This command orchestrates the entire smart deployment workflow.",
+      "description": "Builds the local dependency graph and deployment waves, then exports review-ready graph artifacts in Mermaid, DOT, JSON, or HTML format.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg",
-        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --dry-run",
-        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --validate-only",
-        "<%= config.bin %> <%= command.id %> --source-path force-app --target-org myorg --skip-tests"
+        "<%= config.bin %> <%= command.id %> --source-path force-app --format mermaid --report-dir reports/graphs",
+        "<%= config.bin %> smart-deployment graph export --format html --output reports/dependency-graph.html",
+        "<%= config.bin %> smart-deployment graph export --json --format json"
       ],
       "flags": {
         "json": {
@@ -449,67 +1237,55 @@
           "multiple": false,
           "type": "option"
         },
-        "target-org": {
-          "aliases": [
-            "targetusername",
-            "u"
-          ],
-          "char": "o",
-          "deprecateAliases": true,
-          "name": "target-org",
-          "noCacheDefault": true,
-          "summary": "Username or alias of the target org.",
-          "hasDynamicHelp": true,
+        "source-path": {
+          "description": "Path to the Salesforce source directory used to build the dependency and wave graph.",
+          "name": "source-path",
+          "summary": "Salesforce source path to analyze",
+          "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "dry-run": {
-          "char": "d",
-          "name": "dry-run",
-          "summary": "Preview deployment without executing",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "validate-only": {
-          "char": "v",
-          "name": "validate-only",
-          "summary": "Validate the local wave plan without deploying",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "skip-tests": {
-          "char": "s",
-          "name": "skip-tests",
-          "summary": "Skip running tests during deployment",
-          "allowNo": false,
-          "type": "boolean"
+        "report-dir": {
+          "description": "Defaults to .smart-deployment/reports/graph-export under the analyzed project root.",
+          "name": "report-dir",
+          "summary": "Directory where the selected graph artifact is written",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         },
-        "source-path": {
-          "description": "Defaults to the current working directory when omitted",
-          "name": "source-path",
-          "summary": "Path to the Salesforce project to analyze and deploy",
+        "output": {
+          "description": "Overrides --report-dir and writes the selected graph artifact to this file.",
+          "name": "output",
+          "summary": "Exact output file path for the selected graph format",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "allow-cycle-remediation": {
-          "description": "Applies temporary reversible source edits for simple cycles only",
-          "name": "allow-cycle-remediation",
-          "summary": "Allow conservative cycle remediation for supported ApexClass cycles",
-          "allowNo": false,
-          "type": "boolean"
+        "format": {
+          "char": "f",
+          "description": "Supported formats are mermaid, dot, json, and html.",
+          "name": "format",
+          "summary": "Graph export format",
+          "default": "json",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "mermaid",
+            "dot",
+            "json",
+            "html"
+          ],
+          "type": "option"
         },
         "use-ai": {
-          "description": "Enables provider-backed analysis for deployment prioritization",
           "name": "use-ai",
-          "summary": "Use AI for intelligent priority weighting and dependency inference",
+          "summary": "Use configured AI providers for dependency inference and wave priority analysis before exporting",
           "allowNo": false,
           "type": "boolean"
         },
         "org-type": {
-          "description": "Helps AI provide context-aware recommendations",
           "name": "org-type",
-          "summary": "Organization type context for AI analysis",
+          "summary": "Target org type used by AI wave priority analysis",
           "hasDynamicHelp": false,
           "multiple": false,
           "options": [
@@ -520,45 +1296,51 @@
           "type": "option"
         },
         "industry": {
-          "description": "Provides business context to AI for better prioritization",
           "name": "industry",
-          "summary": "Industry context for AI analysis",
+          "summary": "Industry context used by AI wave priority analysis",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         }
       },
-      "hasDynamicHelp": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "start",
+      "id": "graph:export",
       "pluginAlias": "@jterrats/smart-deployment",
       "pluginName": "@jterrats/smart-deployment",
       "pluginType": "core",
       "strict": true,
-      "summary": "Deploy Salesforce metadata intelligently with automatic wave generation",
+      "summary": "Export dependency and deployment wave graphs",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "start.js"
+        "graph",
+        "export.js"
       ],
       "aliasPermutations": [
-        "smart-deployment:start",
-        "start:smart-deployment"
+        "smart-deployment:graph:export",
+        "graph:smart-deployment:export",
+        "graph:export:smart-deployment",
+        "smart-deployment:export:graph",
+        "export:smart-deployment:graph",
+        "export:graph:smart-deployment"
       ],
       "permutations": [
-        "start"
+        "graph:export",
+        "export:graph"
       ]
     },
-    "status": {
+    "metadata:gaps": {
       "aliases": [
-        "smart-deployment:status"
+        "smart-deployment:metadata:gaps"
       ],
       "args": {},
+      "description": "Scans package manifests and Salesforce source paths, compares detected metadata types against smart-deployment support, and reports safe next steps for unsupported or partially supported metadata.",
       "examples": [
-        "<%= config.bin %> <%= command.id %> --source-path force-app",
-        "<%= config.bin %> <%= command.id %> --target-org myorg --source-path force-app"
+        "<%= config.bin %> <%= command.id %> --source-path force-app --json",
+        "<%= config.bin %> smart-deployment metadata gaps --ai-explain"
       ],
       "flags": {
         "json": {
@@ -576,59 +1358,60 @@
           "multiple": false,
           "type": "option"
         },
-        "target-org": {
-          "aliases": [
-            "targetusername",
-            "u"
-          ],
-          "char": "o",
-          "deprecateAliases": true,
-          "name": "target-org",
-          "noCacheDefault": true,
-          "summary": "Username or alias of the target org.",
-          "hasDynamicHelp": true,
-          "multiple": false,
-          "type": "option"
-        },
         "source-path": {
+          "description": "Path used to locate sfdx-project.json and scan configured package directories.",
           "name": "source-path",
-          "summary": "Path to the Salesforce project containing deployment state",
+          "summary": "Salesforce project or source path to scan",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "ai-explain": {
+          "description": "Adds a deterministic prompt and setup-agents workflow command for Codex-assisted review. The plugin does not call an AI provider directly.",
+          "name": "ai-explain",
+          "summary": "Include workflow-ready AI explanation context",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
-      "hasDynamicHelp": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "status",
+      "id": "metadata:gaps",
       "pluginAlias": "@jterrats/smart-deployment",
       "pluginName": "@jterrats/smart-deployment",
       "pluginType": "core",
       "strict": true,
-      "summary": "Show deployment status",
+      "summary": "Analyze unsupported Salesforce metadata types",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "status.js"
+        "metadata",
+        "gaps.js"
       ],
       "aliasPermutations": [
-        "smart-deployment:status",
-        "status:smart-deployment"
+        "smart-deployment:metadata:gaps",
+        "metadata:smart-deployment:gaps",
+        "metadata:gaps:smart-deployment",
+        "smart-deployment:gaps:metadata",
+        "gaps:smart-deployment:metadata",
+        "gaps:metadata:smart-deployment"
       ],
       "permutations": [
-        "status"
+        "metadata:gaps",
+        "gaps:metadata"
       ]
     },
-    "validate": {
+    "plan:explain": {
       "aliases": [
-        "smart-deployment:validate"
+        "smart-deployment:plan:explain"
       ],
       "args": {},
+      "description": "Builds the same local plan used by start dry-run and explains wave placement, dependency edges, unresolved references, and provider-owned deployment decisions.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --source-path force-app",
-        "<%= config.bin %> <%= command.id %> --source-path force-app --use-ai"
+        "<%= config.bin %> smart-deployment plan explain --use-ai --org-type Sandbox --target-org dev"
       ],
       "flags": {
         "json": {
@@ -662,41 +1445,117 @@
         },
         "source-path": {
           "name": "source-path",
-          "summary": "Path to the Salesforce project to validate",
+          "summary": "Salesforce source path to analyze",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "Accepted for parity with start dry-run; explain never deploys metadata",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "validate-only": {
+          "name": "validate-only",
+          "summary": "Accepted for parity with start validate-only; explain never deploys metadata",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "skip-tests": {
+          "name": "skip-tests",
+          "summary": "Accepted for parity with start dry-run inputs; explain never runs tests",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allow-cycle-remediation": {
+          "name": "allow-cycle-remediation",
+          "summary": "Accepted for parity with start dry-run inputs; explain does not modify sources",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "use-ai": {
           "name": "use-ai",
-          "summary": "Use AI wave validation with the configured provider when available",
+          "summary": "Use configured AI providers for dependency inference and wave priority analysis",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "org-type": {
+          "name": "org-type",
+          "summary": "Target org type used by AI wave priority analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "Production",
+            "Sandbox",
+            "Developer"
+          ],
+          "type": "option"
+        },
+        "industry": {
+          "name": "industry",
+          "summary": "Industry context used by AI wave priority analysis",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "since": {
+          "name": "since",
+          "summary": "Git ref used to explain changed provider-owned metadata decisions",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "auto-activate": {
+          "name": "auto-activate",
+          "summary": "Include Agentforce activation decisions in provider-owned metadata planning",
           "allowNo": false,
           "type": "boolean"
+        },
+        "scope-commits": {
+          "name": "scope-commits",
+          "summary": "Comma-separated commit SHAs or refs to include in the explained plan",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "scope-manifest": {
+          "name": "scope-manifest",
+          "summary": "Path to a JSON commit or story scope manifest",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "validate",
+      "id": "plan:explain",
       "pluginAlias": "@jterrats/smart-deployment",
       "pluginName": "@jterrats/smart-deployment",
       "pluginType": "core",
       "strict": true,
-      "summary": "Validate the local wave plan without deploying",
+      "summary": "Explain why metadata components are placed in deployment waves",
       "enableJsonFlag": true,
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
-        "validate.js"
+        "plan",
+        "explain.js"
       ],
       "aliasPermutations": [
-        "smart-deployment:validate",
-        "validate:smart-deployment"
+        "smart-deployment:plan:explain",
+        "plan:smart-deployment:explain",
+        "plan:explain:smart-deployment",
+        "smart-deployment:explain:plan",
+        "explain:smart-deployment:plan",
+        "explain:plan:smart-deployment"
       ],
       "permutations": [
-        "validate"
+        "plan:explain",
+        "explain:plan"
       ]
     }
   },
-  "version": "1.2.6"
+  "version": "1.4.0"
 }