@salesforce/afv-skills 1.31.0 → 1.32.0

package/skills/platform-sharing-rules-generate/SKILL.md

@@ -1,31 +1,47 @@
 ---
 name: platform-sharing-rules-generate
-description: "Use this skill when users need to create, generate, or modify Salesforce Sharing Rules metadata. TRIGGER when: users mention sharing rules, record sharing, criteria-based sharing, role-based sharing, guest user sharing, portal user sharing, sharingRules, sharingCriteriaRules, sharingGuestRules, sharingOwnerRules, .sharingRules-meta.xml files, or ask to share records with specific roles or groups. Also trigger when users want to configure record-level access beyond org-wide defaults (OWD), share object records with roles, groups, or guest users, or set up Experience Site guest user record visibility. SKIP when: user needs permission sets or profiles (use platform-permission-set-generate), or needs object-level security rather than record-level sharing (use platform-permission-set-generate)."
+description: "Use this skill when users need to create, edit, delete, or manage Salesforce Sharing Rules metadata. TRIGGER when: users mention sharing rules, record sharing, criteria-based sharing, role-based sharing, guest user sharing, sharingRules, sharingCriteriaRules, sharingGuestRules, sharingOwnerRules, .sharingRules-meta.xml files, or ask to share records with specific roles or groups. Also trigger when users want to modify or remove existing sharing rules, or update sharing rule criteria or access levels. DO NOT TRIGGER when user needs permission sets or profiles (use platform-permission-set-generate), or needs object-level security rather than record-level sharing (use platform-permission-set-generate)."
 metadata:
-  version: "1.0"
+  version: "1.1"
+  minApiVersion: "51.0"
+  relatedSkills:
+    - "platform-permission-set-generate"
+    - "platform-custom-object-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # Sharing Rules Generator
 
-Generate Salesforce Sharing Rules metadata to control record-level access beyond org-wide defaults. Supports criteria-based rules, role/group-based owner rules, and guest user rules for Experience Sites.
+Create, edit, and delete Salesforce Sharing Rules metadata to control record-level access beyond org-wide defaults. Supports criteria-based rules, role/group-based owner rules, and guest user rules for Experience Sites.
 
 ## Scope
 
-- **In scope**: Generating `sharingCriteriaRules`, `sharingOwnerRules`, and `sharingGuestRules` metadata; retrieving existing sharing rules from an org; appending new rules to existing files; configuring rules for Guest and Portal profiles.
+- **In scope**: Creating, editing, and deleting `sharingCriteriaRules`, `sharingOwnerRules`, and `sharingGuestRules` metadata; retrieving existing sharing rules from an org; appending new rules to existing files; modifying rule criteria, access levels, or shared-to targets; removing rules from metadata files; configuring rules for Guest and Portal profiles.
 - **Out of scope**: Changing org-wide defaults (OWD/sharing model), creating Experience Sites, configuring permission sets or profiles (use `platform-permission-set-generate`), territory-based sharing rules.
 
 ---
 
 ## Clarifying Questions
 
-Before generating, confirm with the user if not already clear:
+Before proceeding, confirm with the user if not already clear:
 
+### For Create operations:
 - Which object should the sharing rule apply to? (standard or custom object API name)
 - What type of rule? (criteria-based, role/group-based owner rule, or guest user rule)
 - Who should records be shared with? (role name, group, portal role, or guest user nickname)
 - What access level? (Read or Read/Write)
 - For criteria-based rules: what field conditions should match?
 
+### For Edit operations:
+- Which existing rule should be modified? (rule fullName or label)
+- What should change? (access level, shared-to target, criteria, label)
+
+### For Delete operations:
+- Which rule(s) should be removed? (rule fullName or label)
+- Confirm the object the rule belongs to
+
 ---
 
 ## Required Inputs
@@ -48,7 +64,7 @@ Defaults unless specified:
 
 ## Workflow
 
-All steps are sequential. Do not skip or reorder.
+Steps are sequential within each phase. Phase 3 branches by operation type — execute only the matching branch.
 
 ### Phase 1 — Discover
 
@@ -61,28 +77,61 @@ All steps are sequential. Do not skip or reorder.
    sf project retrieve start --metadata "SharingRules:<ObjectName>" --target-org <org>
    ```
 
-### Phase 2 — Determine Rule Type
+### Phase 2 — Determine Operation and Rule Type
+
+4. **Identify the operation** — determine whether the user wants to **create**, **edit**, or **delete** a sharing rule.
+
+5. **Select the rule type** based on user intent. Read `references/rule-types.md` for the complete schema of each type and its required elements.
+
+6. **For Account sharing rules**: the `accountSettings` element is required. Default sub-access levels to `None` unless the user specifies otherwise.
+
+7. **For Guest rules**: the `sharedTo` must use `<guestUser>` with the site guest user's community nickname. Never use `<role>` or `<group>` for guest rules.
+
+### Phase 3 — Execute Operation
+
+#### For Create:
 
-4. **Select the rule type** based on user intent. Read `references/rule-types.md` for the complete schema of each type and its required elements.
+8a. **Construct the XML** following the schema in `references/rule-types.md`. Key structure:
+    - One `.sharingRules-meta.xml` file per object
+    - All rules for the same object go in the same file
+    - If appending to an existing file, add the new rule element inside the existing `<SharingRules>` root
 
-5. **For Account sharing rules**: the `accountSettings` element is required. Default sub-access levels to `None` unless the user specifies otherwise.
+8b. **Name the rule** — derive `<fullName>` from the intent (PascalCase, no spaces, descriptive). Generate a matching `<label>` in Title Case with spaces.
 
-6. **For Guest rules**: the `sharedTo` must use `<guestUser>` with the site guest user's community nickname. Never use `<role>` or `<group>` for guest rules.
+#### For Edit:
 
-### Phase 3 — Generate
+8a. **Locate the target rule** — find the rule by `<fullName>` or `<label>` in the existing `.sharingRules-meta.xml` file.
 
-7. **Construct the XML** following the schema in `references/rule-types.md`. Key structure:
-   - One `.sharingRules-meta.xml` file per object
-   - All rules for the same object go in the same file
-   - If appending to an existing file, add the new rule element inside the existing `<SharingRules>` root
+8b. **Determine modifications** — identify which elements to change (e.g., `<accessLevel>`, `<sharedTo>`, `<criteriaItems>`, `<label>`) and what the new values will be. Do not write yet — all disk writes happen in Phase 5 after user confirmation.
 
-8. **Name the rule** — derive `<fullName>` from the intent (PascalCase, no spaces, descriptive). Generate a matching `<label>` in Title Case with spaces.
+#### For Delete:
 
-9. **Write the file** to `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml`.
+8a. **Locate the target rule** — find the rule by `<fullName>` or `<label>` in the existing `.sharingRules-meta.xml` file.
 
-### Phase 4 — Verify
+8b. **Count remaining rules** — run: `grep -c '<sharingCriteriaRules>\|<sharingOwnerRules>\|<sharingGuestRules>' <file>` to get the total rule count. If the count is 1 (only the rule being deleted), the file must be removed entirely in Phase 5. Do not write yet — all disk writes happen in Phase 5 after user confirmation.
 
-10. **Run the verification checklist** below before presenting output.
+### Phase 4 — Confirm with User   CRITICAL
+
+9. **Present a summary of changes** before writing to disk. You MUST stop and wait for user confirmation. Format the summary as:
+
+    > **Operation:** Create / Edit / Delete
+    > **Object:** `<ObjectName>`
+    > **Rule:** `<fullName>` (`<label>`)
+    > **Changes:** (describe what will be created/modified/removed)
+    >
+    > Proceed? (yes / no / edit)
+
+    **Do NOT write any file changes until the user explicitly confirms.** If the user says "no", abort. If the user says "edit", incorporate their feedback and re-present.
+
+### Phase 5 — Write and Verify
+
+10. **Apply the change** only after user confirmation:
+    - **Create**: Write the file to `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml`.
+    - **Edit**: Update only the elements identified in step 8b; preserve all other elements exactly as they were.
+    - **Delete (rules remain)**: Write the updated file with the target rule removed.
+    - **Delete (last rule)**: Remove the file `<packageDir>/sharingRules/<ObjectName>.sharingRules-meta.xml` entirely.
+
+11. **Run the verification checklist** below and consult `examples/test-cases.md` for scenario-specific expected behaviors before presenting output.
 
 ---
 
@@ -109,6 +158,18 @@ All steps are sequential. Do not skip or reorder.
 - [ ] Does the rule have both `<sharedFrom>` and `<sharedTo>` elements?
 - [ ] Do both use valid `<role>`, `<roleAndSubordinates>`, or `<group>` targets?
 
+### Edit Operation Checks
+- [ ] Was only the intended element modified?
+- [ ] Are all required elements still present after the edit?
+- [ ] Does the modified rule still pass the universal checks above?
+- [ ] Was user confirmation received before writing?
+
+### Delete Operation Checks
+- [ ] Was the correct rule removed (matched by `<fullName>`)?
+- [ ] Is the remaining XML well-formed with proper `<SharingRules>` root?
+- [ ] If no rules remain, was the file removed entirely?
+- [ ] Was user confirmation received before writing?
+
 ### Account-Specific Checks   CRITICAL
 - [ ] If object is Account, is `<accountSettings>` present with all three sub-elements?
 - [ ] Are `<caseAccessLevel>`, `<contactAccessLevel>`, `<opportunityAccessLevel>` all set?
@@ -126,6 +187,10 @@ All steps are sequential. Do not skip or reorder.
 | `includeHVUOwnedRecords` is required on guest rules | Missing it causes deployment failure |
 | Criteria field values must exist as picklist values on the org | Invalid values cause: "Picklist value does not exist" |
 | Never hardcode file paths — resolve from `sfdx-project.json` | Customer projects use custom package directories |
+| Always confirm before writing changes | Prevents accidental creation, modification, or deletion of sharing rules |
+| Edit must preserve unmodified elements | Changing only `accessLevel` must not alter `criteriaItems` or other fields |
+| Delete must remove the entire rule block | Partial deletion leaves invalid XML and causes deployment failures |
+| Delete last rule removes the file | An empty `<SharingRules>` root with no children is invalid metadata |
 
 ---
 
@@ -139,6 +204,10 @@ All steps are sequential. Do not skip or reorder.
 | Picklist value mismatch | Query the org for valid values before generating criteria |
 | Appending duplicates existing rule name | Check existing `<fullName>` values before writing |
 | Guest user nickname not found | Query: `SELECT CommunityNickname FROM User WHERE UserType='Guest' AND IsActive=true` |
+| Editing a rule that doesn't exist locally | Retrieve from org first before attempting edit |
+| Deleting a rule referenced by other automation | Warn the user about potential downstream impact before confirming |
+| Editing changes rule type (e.g., criteria → owner) | Not supported — delete the old rule and create a new one instead |
+| Delete leaves malformed XML | Ensure proper XML structure after removal; validate the file is well-formed |
 
 ---
 
@@ -163,3 +232,4 @@ Deliverables:
 | File | When to read |
 |------|-------------|
 | `references/rule-types.md` | Phase 2 — before generating any rule, to get the complete XML schema for each rule type |
+| `examples/test-cases.md` | Phase 5, step 11 — during verification, to check expected behavior for each scenario type |

package/skills/platform-sharing-rules-generate/examples/test-cases.md

@@ -0,0 +1,381 @@
+# Sharing Rules — Test Cases
+
+Structured test scenarios for create, edit, and delete operations. Each test case defines an input, the expected behavior, and the expected output.
+
+---
+
+## Create Operations
+
+### TC-01: Create a criteria-based sharing rule
+
+**Input:**
+- Object: `Property__c`
+- Rule type: criteria-based
+- Share with: role `RegionalManager`
+- Access level: Read
+- Criteria: `Status__c` equals `Active`
+
+**Expected behavior:**
+1. Discovers SFDX project path and checks for existing `Property__c.sharingRules-meta.xml`
+2. Presents confirmation summary to user and waits for approval
+3. After confirmation, writes the file
+
+**Expected output:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
+    <sharingCriteriaRules>
+        <fullName>ShareActivePropertiesWithRegionalManager</fullName>
+        <accessLevel>Read</accessLevel>
+        <includeRecordsOwnedByAll>true</includeRecordsOwnedByAll>
+        <label>Share Active Properties With Regional Manager</label>
+        <sharedTo>
+            <role>RegionalManager</role>
+        </sharedTo>
+        <criteriaItems>
+            <field>Status__c</field>
+            <operation>equals</operation>
+            <value>Active</value>
+        </criteriaItems>
+    </sharingCriteriaRules>
+</SharingRules>
+```
+
+---
+
+### TC-02: Create a guest user sharing rule
+
+**Input:**
+- Object: `Listing__c`
+- Rule type: guest
+- Share with: guest user with CommunityNickname `PropertySiteGuest`
+- Access level: Read
+- Criteria: `Published__c` equals `true`
+
+**Expected behavior:**
+1. Discovers project path and checks for existing file
+2. Queries org for guest user nickname if not provided
+3. Presents confirmation summary and waits for approval
+4. After confirmation, writes file using `<guestUser>` (not `<role>` or `<group>`)
+
+**Expected output:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
+    <sharingGuestRules>
+        <fullName>SharePublishedListingsWithSiteGuest</fullName>
+        <accessLevel>Read</accessLevel>
+        <includeHVUOwnedRecords>false</includeHVUOwnedRecords>
+        <label>Share Published Listings With Site Guest</label>
+        <sharedTo>
+            <guestUser>PropertySiteGuest</guestUser>
+        </sharedTo>
+        <criteriaItems>
+            <field>Published__c</field>
+            <operation>equals</operation>
+            <value>true</value>
+        </criteriaItems>
+    </sharingGuestRules>
+</SharingRules>
+```
+
+---
+
+### TC-03: Create an Account owner-based sharing rule
+
+**Input:**
+- Object: `Account`
+- Rule type: owner-based
+- Share from: role `SalesDirector`
+- Share to: role and subordinates `SalesTeam`
+- Access level: Edit
+
+**Expected behavior:**
+1. Discovers project path, checks for existing Account sharing rules
+2. Includes `<accountSettings>` with all three sub-elements defaulted to `None`
+3. Presents confirmation summary and waits for approval
+4. After confirmation, writes the file
+
+**Expected output:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<SharingRules xmlns="http://soap.sforce.com/2006/04/metadata">
+    <sharingOwnerRules>
+        <fullName>ShareDirectorAccountsWithSalesTeam</fullName>
+        <accessLevel>Edit</accessLevel>
+        <accountSettings>
+            <caseAccessLevel>None</caseAccessLevel>
+            <contactAccessLevel>None</contactAccessLevel>
+            <opportunityAccessLevel>None</opportunityAccessLevel>
+        </accountSettings>
+        <label>Share Director Accounts With Sales Team</label>
+        <sharedFrom>
+            <role>SalesDirector</role>
+        </sharedFrom>
+        <sharedTo>
+            <roleAndSubordinates>SalesTeam</roleAndSubordinates>
+        </sharedTo>
+    </sharingOwnerRules>
+</SharingRules>
+```
+
+---
+
+### TC-04: Append a rule to an existing file
+
+**Input:**
+- Object: `Property__c` (file already exists with TC-01's rule)
+- Rule type: criteria-based
+- Share with: group `AllAgents`
+- Access level: Edit
+- Criteria: `Price__c` greaterThan `1000000`
+
+**Expected behavior:**
+1. Reads existing file and finds TC-01's rule already present
+2. Does not duplicate existing rule
+3. Presents confirmation showing the new rule will be appended
+4. After confirmation, appends new rule inside existing `<SharingRules>` root
+
+**Expected output:** File contains both TC-01's rule AND the new rule within the same `<SharingRules>` element.
+
+---
+
+## Edit Operations
+
+### TC-05: Edit access level of an existing rule
+
+**Input:**
+- Object: `Property__c`
+- Target rule: `ShareActivePropertiesWithRegionalManager`
+- Change: access level from `Read` to `Edit`
+
+**Expected behavior:**
+1. Locates the rule by `<fullName>` in the existing file
+2. Presents confirmation showing current vs. proposed change:
+   > **Operation:** Edit
+   > **Object:** `Property__c`
+   > **Rule:** `ShareActivePropertiesWithRegionalManager` (Share Active Properties With Regional Manager)
+   > **Changes:** accessLevel: Read → Edit
+   >
+   > Proceed? (yes / no / edit)
+3. Waits for user confirmation
+4. After confirmation, modifies only `<accessLevel>` — all other elements unchanged
+
+**Expected output (changed portion):**
+```xml
+<accessLevel>Edit</accessLevel>
+```
+All other elements (`fullName`, `label`, `sharedTo`, `criteriaItems`, `includeRecordsOwnedByAll`) remain identical.
+
+---
+
+### TC-06: Edit shared-to target of an existing rule
+
+**Input:**
+- Object: `Property__c`
+- Target rule: `ShareActivePropertiesWithRegionalManager`
+- Change: shared-to from role `RegionalManager` to group `PropertyViewers`
+
+**Expected behavior:**
+1. Locates the rule in the file
+2. Presents confirmation showing:
+   > **Changes:** sharedTo: role `RegionalManager` → group `PropertyViewers`
+3. Waits for confirmation
+4. Replaces `<sharedTo>` content only
+
+**Expected output (changed portion):**
+```xml
+<sharedTo>
+    <group>PropertyViewers</group>
+</sharedTo>
+```
+
+---
+
+### TC-07: Edit criteria of an existing rule
+
+**Input:**
+- Object: `Property__c`
+- Target rule: `ShareActivePropertiesWithRegionalManager`
+- Change: update criteria from `Status__c equals Active` to `Status__c equals Active` AND `Region__c equals West`
+
+**Expected behavior:**
+1. Locates the rule in the file
+2. Presents confirmation showing current criteria vs. proposed criteria
+3. Waits for confirmation
+4. Replaces `<criteriaItems>` elements
+
+**Expected output (changed portion):**
+```xml
+<criteriaItems>
+    <field>Status__c</field>
+    <operation>equals</operation>
+    <value>Active</value>
+</criteriaItems>
+<criteriaItems>
+    <field>Region__c</field>
+    <operation>equals</operation>
+    <value>West</value>
+</criteriaItems>
+```
+
+---
+
+### TC-08: Edit attempt on non-existent rule
+
+**Input:**
+- Object: `Property__c`
+- Target rule: `NonExistentRule`
+- Change: access level to `Edit`
+
+**Expected behavior:**
+1. Searches for the rule by `<fullName>` in the file
+2. Rule not found — reports error to user
+3. Suggests listing available rules in the file and asks user to clarify
+
+**Expected output:** No file changes. Error message listing available rule names in the file.
+
+---
+
+## Delete Operations
+
+### TC-09: Delete a single rule (other rules remain)
+
+**Input:**
+- Object: `Property__c` (file contains 2 rules)
+- Delete rule: `ShareActivePropertiesWithRegionalManager`
+
+**Expected behavior:**
+1. Locates the rule in the file
+2. Presents confirmation:
+   > **Operation:** Delete
+   > **Object:** `Property__c`
+   > **Rule:** `ShareActivePropertiesWithRegionalManager` (Share Active Properties With Regional Manager)
+   > **Changes:** Remove this criteria-based sharing rule entirely. 1 other rule(s) will remain in the file.
+   >
+   > Proceed? (yes / no / edit)
+3. Waits for confirmation
+4. Removes the entire `<sharingCriteriaRules>` block for that rule
+5. Other rules in the file remain intact
+
+**Expected output:** File retains `<SharingRules>` root and all other rules, with the deleted rule's block completely removed.
+
+---
+
+### TC-10: Delete the last rule in a file
+
+**Input:**
+- Object: `Listing__c` (file contains only 1 rule)
+- Delete rule: `SharePublishedListingsWithSiteGuest`
+
+**Expected behavior:**
+1. Locates the rule — confirms it is the only rule in the file
+2. Presents confirmation warning that the entire file will be removed:
+   > **Operation:** Delete
+   > **Object:** `Listing__c`
+   > **Rule:** `SharePublishedListingsWithSiteGuest` (Share Published Listings With Site Guest)
+   > **Changes:** Remove this guest sharing rule. This is the last rule — the entire file `Listing__c.sharingRules-meta.xml` will be deleted.
+   >
+   > Proceed? (yes / no / edit)
+3. Waits for confirmation
+4. Deletes the entire file
+
+**Expected output:** File `Listing__c.sharingRules-meta.xml` no longer exists.
+
+---
+
+### TC-11: Delete with user declining confirmation
+
+**Input:**
+- Object: `Account`
+- Delete rule: `ShareDirectorAccountsWithSalesTeam`
+- User response to confirmation: "no"
+
+**Expected behavior:**
+1. Locates the rule
+2. Presents confirmation
+3. User says "no"
+4. Aborts — no changes written
+
+**Expected output:** No file changes. Acknowledgment that the operation was cancelled.
+
+---
+
+### TC-12: Delete attempt on non-existent rule
+
+**Input:**
+- Object: `Property__c`
+- Delete rule: `RuleThatDoesNotExist`
+
+**Expected behavior:**
+1. Searches for the rule by `<fullName>` in the file
+2. Rule not found — reports error
+3. Lists available rules and asks user to clarify
+
+**Expected output:** No file changes. Error message listing available rule names.
+
+---
+
+## Confirmation Flow Tests
+
+### TC-13: User confirms with "yes"
+
+**Input:** Any create/edit/delete operation where user responds "yes" to confirmation.
+
+**Expected behavior:** Changes are written to disk as presented in the summary.
+
+---
+
+### TC-14: User responds with "edit" and provides feedback
+
+**Input:**
+- Create operation for a criteria rule
+- User responds "edit" to confirmation with: "Change the access level to Edit instead of Read"
+
+**Expected behavior:**
+1. Original summary presented
+2. User says "edit" with feedback
+3. Incorporates feedback (changes `accessLevel` to `Edit`)
+4. Re-presents updated summary
+5. Waits for new confirmation before writing
+
+---
+
+### TC-15: User declines with "no"
+
+**Input:** Any create/edit/delete operation where user responds "no" to confirmation.
+
+**Expected behavior:** No file changes. Operation aborted with acknowledgment.
+
+---
+
+## Edge Cases
+
+### TC-16: Edit that would change rule type
+
+**Input:**
+- Object: `Property__c`
+- Target rule: `ShareActivePropertiesWithRegionalManager` (criteria rule)
+- Change: convert to owner-based rule
+
+**Expected behavior:**
+1. Detects that the change would alter the rule type
+2. Informs user this is not supported as an edit
+3. Suggests: delete the existing rule and create a new one with the desired type
+
+**Expected output:** No file changes. Guidance to user about delete + create workflow.
+
+---
+
+### TC-17: Create rule with duplicate fullName
+
+**Input:**
+- Object: `Property__c` (file already contains rule `ShareActivePropertiesWithRegionalManager`)
+- Create a new rule also named `ShareActivePropertiesWithRegionalManager`
+
+**Expected behavior:**
+1. Reads existing file, finds duplicate `<fullName>`
+2. Informs user of the conflict
+3. Suggests an alternative name or asks user to choose
+
+**Expected output:** No file changes until conflict is resolved.