Deployment assistant: suggest Browserforce browser actions, and link each setting to its documentation

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [beta] (main)
 
+- [Browser deployment action](https://sfdx-hardis.cloudity.com/salesforce-devops-work-on-user-story-deployment-actions-browser/#deployment-errors-a-browser-action-solves):
+  - The deployment assistant suggests it for the errors it can solve, with the command that adds it to your Pull Request.
+  - The AI deployment assistant and the coding agent that fixes deployment errors suggest it too.
+  - Each Browserforce setting links to its documentation page.
 - [hardis:doc:flow2markdown](https://sfdx-hardis.cloudity.com/hardis/doc/flow2markdown/) and [hardis:doc:project2markdown](https://sfdx-hardis.cloudity.com/hardis/doc/project2markdown/): Flow diagrams drawn with Docker no longer fail with a permission error in the sfdx-hardis Docker images.
 - [hardis:doc:mkdocs-to-cf](https://sfdx-hardis.cloudity.com/hardis/doc/mkdocs-to-cf/) and [hardis:doc:mkdocs-to-salesforce](https://sfdx-hardis.cloudity.com/hardis/doc/mkdocs-to-salesforce/): the site is built with the Zensical Docker image when Zensical cannot be installed with pip, as in the Ubuntu Docker image.
 - GitHub: QuickDeploy finds the validation of Pull Requests merged long after they were created (closed Pull Requests are now searched by update date instead of creation date).

build.cjs

@@ -257,17 +257,32 @@ class SfdxHardisBuilder {
       "If you see a deployment error which is not here yet, please [add it in this file](https://github.com/hardisgroupcom/sfdx-hardis/blob/main/src/common/utils/deployTipsList.ts) :)",
       ""
     ];
+    // The committed doc pages are in English, whatever SFDX_HARDIS_LANG the maintainer has set
+    const previousLang = process.env.SFDX_HARDIS_LANG;
+    process.env.SFDX_HARDIS_LANG = "en";
+    const { reinitI18n } = await import("./lib/common/utils/i18n.js");
+    reinitI18n();
+    const { buildTipDeploymentAction, formatDeploymentActionHint } = await import("./lib/common/utils/deployTipActions.js");
     for (const tip of deployTips) {
       const linkName = `sf-deployment-assistant/${tip.label.replace(/[^a-zA-Z0-9 -]|\s/g, '-')}.md`
       const tipFile = `./docs/` + linkName;
-      this.buildIndividualMarkdownPageForTip(tip, tipFile);
-      this.buildMainDeployFixesMarkdown(tip, deployTipsMd, linkName);
+      // The placeholders ({1}...) stay as they are: the page describes every occurrence of the error
+      const deploymentAction = await buildTipDeploymentAction(tip, []);
+      const actionMd = deploymentAction ? formatDeploymentActionHint(deploymentAction, "markdown") : [];
+      this.buildIndividualMarkdownPageForTip(tip, tipFile, actionMd);
+      this.buildMainDeployFixesMarkdown(tip, deployTipsMd, linkName, actionMd);
     }
+    if (previousLang === undefined) {
+      delete process.env.SFDX_HARDIS_LANG;
+    } else {
+      process.env.SFDX_HARDIS_LANG = previousLang;
+    }
+    reinitI18n();
     this.writeFileIfChanged(deployTipsDocFile, deployTipsMd.join("\n") + "\n");
     console.log("Written doc file " + deployTipsDocFile);
   }
 
-  buildMainDeployFixesMarkdown(tip, deployTipsMd, linkName) {
+  buildMainDeployFixesMarkdown(tip, deployTipsMd, linkName, actionMd = []) {
     if (!tip.label) {
       throw new Error(`Missing label for ${JSON.stringify(tip)}`);
     }
@@ -290,11 +305,14 @@ class SfdxHardisBuilder {
     deployTipsMd.push("```shell");
     deployTipsMd.push(...tip.tip.split("\n"));
     deployTipsMd.push("```");
+    if (actionMd.length > 0) {
+      deployTipsMd.push(...["", "**Deployment action**", "", ...actionMd]);
+    }
     deployTipsMd.push("");
     deployTipsMd.push("---");
   }
 
-  buildIndividualMarkdownPageForTip(tip, tipFile) {
+  buildIndividualMarkdownPageForTip(tip, tipFile, actionMd = []) {
     const errorDescription = tip?.examples?.length > 0 ? tip.examples[0] :
       tip?.expressionString?.length > 0 ? tip?.expressionString[0] :
         tip.expressionRegex[0].toString().replace("/Error", "Error").replace("/gm", "");
@@ -324,6 +342,9 @@ class SfdxHardisBuilder {
     tipFileMd.push("```shell");
     tipFileMd.push(...tip.tip.split("\n"));
     tipFileMd.push("```");
+    if (actionMd.length > 0) {
+      tipFileMd.push(...["", "## Deployment action", "", ...actionMd]);
+    }
     this.writeFileIfChanged(tipFile, tipFileMd.join("\n") + "\n");
   }
 

docs/prompt-templates/PROMPT_CODING_AGENT_FIX_DEPLOYMENT_ERRORS.md

@@ -29,6 +29,7 @@ You are a Salesforce developer assistant. Your task is to fix deployment errors
 - Focus on fixing the root cause in the local metadata files
 - If a fix requires removing a reference to something that does not exist in the target org, remove it from the local file
 - If a fix requires adding a missing dependency, add it to the local metadata files
+- When an error comes with a "Deployment action" command (`sf hardis:project:action:create ...`), the error is solved by a deployment action, not by a metadata change: run that command (it only writes a local configuration file) and report it in the summary with the notes that come with it. When its notes list values to replace (like OBJECT_NAME), find them first in the local sources or by querying the target org; never run a command that still holds one, and if you cannot find them, do not run it and explain what to replace
 
 ## DEPLOYMENT ERRORS TO FIX
 

docs/prompt-templates/PROMPT_SOLVE_DEPLOYMENT_ERROR.md

@@ -6,9 +6,10 @@ description: Prompt template for PROMPT_SOLVE_DEPLOYMENT_ERROR
 # PROMPT_SOLVE_DEPLOYMENT_ERROR
 
 ## Variables
-| Name      | Description                                                   | Example                                                    |
-|:----------|:--------------------------------------------------------------|:-----------------------------------------------------------|
-| **ERROR** | The Salesforce deployment error message to analyze and solve. | `Cannot deploy component: missing field 'X' on object 'Y'` |
+| Name                        | Description                                                                                                                     | Example                                                                                                                                                                                                    |
+|:----------------------------|:--------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **ERROR**                   | The Salesforce deployment error message to analyze and solve.                                                                   | `Cannot deploy component: missing field 'X' on object 'Y'`                                                                                                                                                 |
+| **DEPLOYMENT_ACTION_HINTS** | What sfdx-hardis deployment actions can do that a metadata deployment cannot (Setup settings applied in a browser...), or None. | `A sfdx-hardis deployment action of type "browser" applies Salesforce Setup settings that the Metadata API cannot deploy. Its settings:`<br>`  - recordTypes: RecordTypes - Deletes inactive record types` |
 
 ## Prompt
 
@@ -25,6 +26,7 @@ You are a Salesforce release manager using Salesforce CLI commands to perform de
     - Provide a step-by-step solution to resolve the error.
     - If applicable, include the correct sfdx source format or XML example.
     - Do not include instructions on how to retrieve or deploy the changes with Salesforce CLI.
+    - When the error comes from a setting that one of the deployment actions below can apply, suggest that deployment action, with its command.
 
 3. {{VARIABLE_FORMATTING_REQUIREMENTS}}
 
@@ -33,6 +35,9 @@ You are a Salesforce release manager using Salesforce CLI commands to perform de
 - The deployment error returned by Salesforce CLI is:
 {{ERROR}}
 
+- The sfdx-hardis deployment actions that can solve what a metadata deployment cannot:
+{{DEPLOYMENT_ACTION_HINTS}}
+
 {{VARIABLE_ADDITIONAL_INSTRUCTIONS}}
 
 ```

docs/salesforce-deployment-agent-error-list.md

@@ -151,6 +151,18 @@ You need to manually delete record type {1} in target org
 - Delete record type {1}
 ```
 
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
+
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Delete record type {1}" --browser-setting recordTypes --browser-config '{"deletions":[{"fullName":"{1}"}]}'
+```
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/recordTypes/
+
 ---
 ## [Can not find folder](sf-deployment-assistant/Can-not-find-folder.md)
 
@@ -749,6 +761,18 @@ Contacts to multiple accounts be activated in the target org.
 "features": ["ContactsToMultipleAccounts"]
 ```
 
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
+
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Enable Contacts to Multiple Accounts" --browser-setting relateContactToMultipleAccounts --browser-config '{"enabled":true}'
+```
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/relateContactToMultipleAccounts/
+
 ---
 ## [Missing feature Chatter Collaboration Group](sf-deployment-assistant/Missing-feature-Chatter-Collaboration-Group.md)
 
@@ -1073,9 +1097,24 @@ Go manually make the change in the target org, so the deployment will pass
 Sources have references to value {1} of picklist {2}
 - If picklist {2} is standard, add the picklist to sfdx sources by using "sf project retrieve start -m StandardValueSet:{2}", then save again
 - Else, perform a search in all code of {1}, then remove XML tags referring to {1} (for example in record types metadatas)
+- If value {1} exists but is inactive in the target org, a deployment action can activate it: replace OBJECT_NAME by the object of picklist {2} (or, for a standard value set, use "metadataType":"StandardValueSet" and "metadataFullName":"{2}")
+
+```
+
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
 
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Activate value {1} of picklist {2}" --browser-setting picklists --browser-config '{"picklistValues":[{"metadataType":"CustomField","metadataFullName":"OBJECT_NAME.{2}","value":"{1}","active":true}]}'
 ```
 
+Before running it, replace OBJECT_NAME in the command with the real value.
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/picklists/
+
 ---
 ## [Please choose a different name](sf-deployment-assistant/Please-choose-a-different-name.md)
 
@@ -1217,6 +1256,100 @@ If you changed a field from MasterDetail to Lookup, you must do it manually in t
 Go to Email -> Deliverability -> Select value "All emails"
 ```
 
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
+
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Allow all emails in Deliverability" --browser-setting emailDeliverability --browser-config '{"accessLevel":"All email"}'
+```
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/emailDeliverability/
+
+---
+## [Shared Activities can not be deployed](sf-deployment-assistant/Shared-Activities-can-not-be-deployed.md)
+
+**Detection**
+
+- String: `You can't use the Tooling API or Metadata API to enable or disable Shared Activities`
+
+**Resolution**
+
+```shell
+The Metadata API can not change Shared Activities (Allow Users to Relate Multiple Contacts to Tasks and Events)
+- Remove allowUsersToRelateMultipleContactsToTasksAndEvents from Activities.settings-meta.xml in your sources
+- To enable it, go to Setup -> Activity Settings in the target org, or use a deployment action
+- Once enabled, it can not be disabled (only Salesforce support can)
+```
+
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
+
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Enable Shared Activities" --browser-setting activitySettings --browser-config '{"allowUsersToRelateMultipleContactsToTasksAndEvents":true}'
+```
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/activitySettings/
+
+---
+## [Lightning Experience theme not found](sf-deployment-assistant/Lightning-Experience-theme-not-found.md)
+
+**Detection**
+
+- RegExp: `no LightningExperienceTheme named (.*) found`
+
+**Resolution**
+
+```shell
+Lightning Experience theme {1} is not in the target org
+- If {1} is a custom theme, add LightningExperienceTheme:{1} to your sources
+- If {1} is a standard theme (Lightning, LightningBlue...), the Metadata API can not activate it: remove activeThemeName from LightningExperience.settings-meta.xml in your sources, then activate the theme in Setup -> Themes and Branding, or with a deployment action
+```
+
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
+
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Activate Lightning Experience theme {1}" --browser-setting lightningExperienceSettings --browser-config '{"activeThemeName":"{1}"}'
+```
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/lightningExperienceSettings/
+
+---
+## [History tracking not enabled on object](sf-deployment-assistant/History-tracking-not-enabled-on-object.md)
+
+**Detection**
+
+- RegExp: `The entity: (.*) does not have history tracking enabled`
+
+**Resolution**
+
+```shell
+A field tracks its history, but history tracking is not enabled on object {1} in the target org
+- Enable it in the sources: add <enableHistory>true</enableHistory> to the object {1} metadata and deploy it with the field
+- For a Person Account field, the Metadata API can not enable it: use Setup -> Object Manager -> {1} -> Fields & Relationships -> Set History Tracking, or a deployment action
+```
+
+**Deployment action**
+
+A deployment action can solve this error. Create it on the Pull Request of the current branch:
+
+```shell
+sf hardis:project:action:create --agent --scope pr --pr-id current --when pre-deploy --type browser --label "Enable history tracking on {1}" --browser-setting historyTracking --browser-config '[{"objectApiName":"{1}","enableHistoryTracking":true}]'
+```
+
+A deployment check only simulates a browser action. If this check still fails on this error once the action is created, apply the setting once in the target org with the Run in another org button of the VS Code Deployment Actions tab, or with sf hardis:project:action:run --select-org, then run the check again.
+
+Documentation: https://amtrack.github.io/sfdx-browserforce-plugin/settings/historyTracking/
+
 ---
 ## [Sort order must be in sequential order](sf-deployment-assistant/Sort-order-must-be-in-sequential-order.md)