@jterrats/smart-deployment 1.2.5 → 1.3.1

package/oclif.manifest.json

@@ -338,6 +338,198 @@
         "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"
@@ -364,16 +556,9 @@
           "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,
+          "summary": "Target Salesforce org alias or username for remote deployment resume",
+          "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
@@ -398,7 +583,7 @@
           "type": "option"
         }
       },
-      "hasDynamicHelp": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
       "id": "resume",
       "pluginAlias": "@jterrats/smart-deployment",
@@ -421,6 +606,119 @@
         "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"
@@ -431,7 +729,9 @@
         "<%= 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 --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": {
@@ -492,6 +792,14 @@
           "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",
@@ -526,6 +834,45 @@
           "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"
+        },
+        "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": true,
@@ -577,16 +924,9 @@
           "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,
+          "summary": "Target Salesforce org alias or username for remote deployment status refresh",
+          "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
@@ -598,7 +938,7 @@
           "type": "option"
         }
       },
-      "hasDynamicHelp": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
       "id": "status",
       "pluginAlias": "@jterrats/smart-deployment",
@@ -669,11 +1009,25 @@
         },
         "use-ai": {
           "name": "use-ai",
-          "summary": "Use AI wave validation with the configured provider when available",
+          "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"
+        }
+      },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
       "id": "validate",
@@ -696,7 +1050,429 @@
       "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 --target-org dev --report-dir reports/deployment-plan",
+        "<%= config.bin %> smart-deployment ci preset --validation-mode warn-only --skip-tests"
+      ],
+      "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": "Path to the Salesforce source directory used to build the deployment plan.",
+          "name": "source-path",
+          "summary": "Salesforce source path to analyze",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "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": [
+            "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": "ci:preset",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Run the CI deployment planning preset",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "ci",
+        "preset.js"
+      ],
+      "aliasPermutations": [
+        "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": [
+        "ci:preset",
+        "preset:ci"
+      ]
+    },
+    "graph:export": {
+      "aliases": [
+        "smart-deployment:graph:export"
+      ],
+      "args": {},
+      "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 --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": {
+          "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 and wave graph.",
+          "name": "source-path",
+          "summary": "Salesforce source path to analyze",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "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"
+        },
+        "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"
+        },
+        "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": {
+          "name": "use-ai",
+          "summary": "Use configured AI providers for dependency inference and wave priority analysis before exporting",
+          "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"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "graph:export",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Export dependency and deployment wave graphs",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "graph",
+        "export.js"
+      ],
+      "aliasPermutations": [
+        "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": [
+        "graph:export",
+        "export:graph"
+      ]
+    },
+    "plan:explain": {
+      "aliases": [
+        "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 %> smart-deployment plan explain --use-ai --org-type Sandbox --target-org dev"
+      ],
+      "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": "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 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": "plan:explain",
+      "pluginAlias": "@jterrats/smart-deployment",
+      "pluginName": "@jterrats/smart-deployment",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Explain why metadata components are placed in deployment waves",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "plan",
+        "explain.js"
+      ],
+      "aliasPermutations": [
+        "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": [
+        "plan:explain",
+        "explain:plan"
+      ]
     }
   },
-  "version": "1.2.5"
+  "version": "1.3.1"
 }