@salesforce/afv-skills 1.21.0 → 1.23.0

package/skills/platform-data-manage/references/test-data-patterns.md

@@ -0,0 +1,98 @@
+<!-- Parent: platform-data-manage/SKILL.md -->
+# Test Data Patterns Guide
+
+Best practices for creating realistic and effective test data.
+
+## Factory Pattern
+
+### Standard Implementation
+
+```apex
+public class TestDataFactory_Account {
+
+    public static List<Account> create(Integer count) {
+        return create(count, true);
+    }
+
+    public static List<Account> create(Integer count, Boolean doInsert) {
+        List<Account> records = new List<Account>();
+        for (Integer i = 0; i < count; i++) {
+            records.add(buildRecord(i));
+        }
+        if (doInsert) {
+            insert records;
+        }
+        return records;
+    }
+
+    private static Account buildRecord(Integer index) {
+        return new Account(
+            Name = 'Test Account ' + index,
+            Industry = 'Technology'
+        );
+    }
+}
+```
+
+### Key Principles
+
+1. **Always create in lists** - Support bulk operations
+2. **Provide doInsert parameter** - Caller controls insertion
+3. **Track IDs for cleanup** - Return inserted records
+4. **Use realistic data** - Valid picklist values
+
+## Record Count Recommendations
+
+| Test Scenario | Record Count | Why |
+|---------------|--------------|-----|
+| Basic unit test | 1-10 | Quick validation |
+| Trigger testing | 201 | Batch boundary |
+| Flow testing | 200 | Single transaction |
+| Batch Apex | 500+ | Multiple batches |
+| Performance | 1000+ | Stress testing |
+
+## Edge Cases to Test
+
+### Null Values
+```apex
+account.Industry = null;  // Test null handling
+```
+
+### Boundary Values
+```apex
+account.Name = 'A';  // Min length
+account.Name = String.valueOf('X').repeat(255);  // Max length
+```
+
+### Special Characters
+```apex
+account.Name = 'Test & "Special" <Characters>';
+```
+
+### Date Boundaries
+```apex
+opp.CloseDate = Date.today();  // Today
+opp.CloseDate = Date.today().addDays(-1);  // Yesterday
+opp.CloseDate = Date.newInstance(2000, 1, 1);  // Old date
+```
+
+## Relationship Testing
+
+### Create Hierarchy
+```apex
+// Create parent first
+List<Account> accounts = TestDataFactory_Account.create(10);
+
+// Create children with parent references
+List<Contact> contacts = TestDataFactory_Contact.createForAccounts(
+    new List<Id>(new Map<Id, Account>(accounts).keySet()),
+    5  // 5 contacts per account
+);
+```
+
+## Best Practices
+
+1. **Avoid hardcoded IDs** - Use dynamic references
+2. **Create all required fields** - Prevent validation errors
+3. **Use unique values** - Prevent duplicate errors
+4. **Document patterns** - Explain test scenarios

package/skills/platform-docs-get/README.md

@@ -0,0 +1,66 @@
+# platform-docs-get
+
+## What it is
+
+`platform-docs-get` is a **prompt-only skill**.
+
+It gives a practical retrieval playbook for official Salesforce docs on the public web, especially when:
+- `developer.salesforce.com` pages are JS-heavy
+- `help.salesforce.com` pages return shell content
+- `architect.salesforce.com` / `admin.salesforce.com` pages need browser-rendered extraction
+- `lightningdesignsystem.com` pages contain official SLDS guidance
+- the real answer is on a child page, not the guide homepage
+
+## What it is not
+
+This skill does not include:
+- local corpus workflows
+- indexing
+- benchmark workflows
+- any required helper CLI dependency
+- PDF fallback guidance
+
+## Use it for
+
+- official Salesforce docs lookup
+- hard-to-fetch Help articles
+- Apex / API / LWC / Agentforce documentation grounding
+- deciding when to follow child links from broad official guide pages
+- rejecting weak results such as shells, landing pages, and third-party summaries
+
+## Optional utility
+
+A tiny wrapper is available for official Salesforce doc URLs:
+
+```bash
+python3 skills/platform-docs-get/scripts/extract_salesforce_doc.py \
+  --url "https://help.salesforce.com/s/articleView?id=service.miaw_security.htm&type=5" \
+  --pretty
+```
+
+Behavior:
+- automatically routes `help.salesforce.com` URLs into the dedicated Help extractor
+- supports official Salesforce-owned doc hosts such as `developer.salesforce.com`, `architect.salesforce.com`, `admin.salesforce.com`, `lightningdesignsystem.com`, and other official Salesforce documentation pages
+- supports optional best-effort stealth mode via `--stealth`
+
+Dependencies for the helper scripts live in:
+- `skills/platform-docs-get/requirements.txt`
+
+The installer sets up an isolated runtime under `~/.claude/.platform-docs-get-runtime`, installs those Python packages there, and installs the Playwright Chromium browser automatically during install/update.
+
+The underlying Help extractor is also available directly at:
+
+```bash
+python3 skills/platform-docs-get/scripts/extract_help_salesforce.py \
+  --url "https://help.salesforce.com/s/articleView?id=service.miaw_security.htm&type=5" \
+  --pretty
+```
+
+## Key idea
+
+Keep retrieval:
+- **official-source-first**
+- **HTML-only**
+- **targeted**
+- **child-link aware**
+- **strict about exact concept matching**

package/skills/platform-docs-get/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: platform-docs-get
+description: "Official Salesforce documentation retrieval skill. Use when you need authoritative Salesforce docs from developer.salesforce.com, help.salesforce.com, architect.salesforce.com, admin.salesforce.com, or lightningdesignsystem.com, especially when pages are JS-heavy, shell-rendered, or hard to extract with naive fetching. Use to ground answers in official Salesforce sources instead of third-party blogs or summaries. TRIGGER when: user asks for official Salesforce documentation, Apex or API reference, LWC docs, Agentforce docs, setup or help articles, or any doc from a Salesforce-owned domain. DO NOT TRIGGER when: user is asking for a code change, deployment task, or anything not requiring documentation retrieval — use the appropriate sf-* skill instead."
+metadata:
+  version: "1.1"
+---
+
+# platform-docs-get
+
+Use this skill to retrieve and ground answers in **official Salesforce documentation on the public web**.
+
+This skill provides a **reliable online retrieval playbook** for Salesforce docs that are hard to fetch, especially `help.salesforce.com`, JS-heavy `developer.salesforce.com`, Lightning Design System docs on `lightningdesignsystem.com`, and other official Salesforce-owned doc pages such as `architect.salesforce.com` and `admin.salesforce.com`.
+
+Optional extraction scripts are available in `scripts/` — see the Reference File Index below.
+
+## Scope
+
+| | |
+|---|---|
+| **In scope** | Official Salesforce doc retrieval: Apex, API, LWC, metadata, Agentforce, setup articles, SLDS, architect/admin guidance |
+| **Out of scope** | Third-party blogs, PDF fallback, local corpus indexing, benchmark workflows, generating code or metadata |
+
+## Required Inputs
+
+Before fetching, identify:
+- The exact concept, identifier, class, method, or feature name being requested
+- The likely doc family (developer docs, help articles, design system, architect/admin)
+
+No additional setup is required to use the retrieval playbook in this skill. The optional extraction scripts require `playwright` — see `requirements.txt`.
+
+## Official Sources Only
+
+Prefer Salesforce-owned documentation sources:
+- `developer.salesforce.com`
+- `help.salesforce.com`
+- `architect.salesforce.com`
+- `admin.salesforce.com`
+- `lightningdesignsystem.com`
+- other official Salesforce documentation pages when Salesforce uses them as the source of truth
+
+Avoid third-party blogs, videos, or summary articles unless the user explicitly asks for them.
+
+Do **not** fall back to PDFs.
+
+## Retrieval Workflow
+
+### 1. Classify the request first
+
+Before fetching anything, identify the likely doc family.
+
+| Family | Typical Source | Use For |
+|---|---|---|
+| Developer docs | `developer.salesforce.com/docs/...` | Apex, APIs, LWC, metadata, Agentforce developer docs |
+| Help docs | `help.salesforce.com/...` | setup, admin, product configuration |
+| Architect/Admin docs | `architect.salesforce.com/...`, `admin.salesforce.com/...` | best practices, patterns, well-architected guidance, admin enablement |
+| Design system docs | `lightningdesignsystem.com/...` | SLDS, Cosmos, design tokens, component and styling guidance |
+| Legacy atlas docs | `developer.salesforce.com/docs/atlas.en-us.*` | older official guide and reference docs |
+
+### 2. Identify the exact concept
+
+Extract the real target before you search:
+- exact API/class/method name
+- exact feature name
+- exact product phrase
+- exact setup concept
+
+Examples:
+- `Lightning Message Service`
+- `Wire Service`
+- `System.StubProvider`
+- `Agentforce Actions`
+- `Messaging for In-App and Web allowed domains`
+
+### 3. Prefer targeted official retrieval
+
+Do **not** broad-crawl Salesforce docs.
+
+Instead:
+1. identify the most likely official guide root or article
+2. if search is needed, restrict it to official Salesforce domains only
+3. fetch that official page
+4. check whether the **exact concept actually appears on the page**
+5. if not, inspect and follow the most relevant **1–3 official child links**
+6. stop once you have grounded evidence
+
+### 4. Do not stop at broad landing pages
+
+A guide landing page is **not enough** unless it clearly contains the exact requested concept.
+
+This is especially important for:
+- LWC docs
+- Agentforce docs
+- broad platform guide homepages
+- help landing pages that link to the real article
+
+### 5. For `developer.salesforce.com`
+
+Use this playbook:
+- start with the most likely official guide root
+- if the page is JS-heavy, prefer browser-rendered extraction
+- check whether the exact concept appears on the page
+- if the concept is missing, inspect official child links and follow the best matching 1–3 links
+- prefer exact concept pages over broad guide roots
+- legacy atlas pages are valid if they are the real official reference for the concept
+
+### 6. For `help.salesforce.com`
+
+Help pages often fail with naive fetching.
+
+Use this playbook:
+- prefer exact `articleView?id=...` URLs when available
+- use browser-rendered extraction when plain fetch returns shell content
+- treat outputs like `Loading`, `Sorry to interrupt`, `CSS Error`, or mostly chrome/navigation text as **failed extraction**, not evidence
+- look for the **real article body**, not just header, nav, or footer text
+- reject shell pages and soft-404 pages such as:
+  - "We looked high and low but couldn't find that page"
+  - generic empty help shells
+- if starting from a nearby guide or hub page, follow linked Help articles until you reach the real article body
+- if extraction still fails after targeted retries, return the best official Help URLs you found and explicitly say that article-body extraction was unsuccessful
+
+## Acceptance Rules
+
+A page is good enough to answer from only when at least one of these is true:
+- the exact identifier appears on the page
+- the exact concept phrase appears on the page
+- multiple query-specific phrases appear in the correct official context
+
+A page is **not** good enough when:
+- it is only a broad landing page
+- it is a shell page with little real article text
+- it is from the wrong product area
+- it does not contain the requested identifier or concept
+- it is a third-party explanation when an official page should exist
+
+## Rejection Rules
+
+Reject these as final evidence:
+- broad guide homepages without the exact concept
+- release notes when a concept/reference page is expected
+- admin blog posts when developer docs are requested
+- third-party blogs when official docs are available
+- shell-rendered pages with no real article body
+- pages whose titles sound right but whose body does not contain the requested concept
+
+## Grounding Requirements
+
+When answering, include:
+1. guide/article title
+2. exact official URL
+3. source type:
+   - developer doc page
+   - atlas reference page
+   - help article page
+4. any caveat if extraction was partial or browser-rendered
+
+If evidence is weak, say so plainly.
+
+## Examples
+
+### Example: Lightning Message Service
+Do **not** stop at the general LWC guide root.
+Find the exact LWC page for Lightning Message Service or follow the most relevant child links from the LWC docs until the exact concept appears.
+
+### Example: Wire Service
+Do **not** answer from the LWC homepage unless `Wire Service` is actually present there.
+Follow the relevant child doc page for wire service or wire adapters.
+
+### Example: Agentforce Actions
+Do **not** answer from a broad Agentforce landing page or a blog post.
+Find the official Agentforce developer page for actions, or follow the best matching child pages from the official Agentforce docs.
+
+### Example: Messaging for In-App and Web allowed domains
+Prefer official Help articles and browser-rendered extraction.
+Reject generic help shells. Follow linked Help articles from nearby official messaging docs if needed.
+
+### Example: System.StubProvider
+Prefer the official Salesforce reference/developer page where the exact identifier appears.
+Do not substitute a broader Apex landing page if the identifier is absent.
+
+## Non-Goals
+
+This skill should **not**:
+- maintain a local documentation corpus
+- rely on a local index
+- use PDF fallback
+- run benchmark workflows
+- depend on repo-specific scripts to be useful
+
+## Output Expectations
+
+For each retrieval, include:
+1. Guide or article title
+2. Exact official URL
+3. Source type (developer doc page / atlas reference page / help article page)
+4. Any caveat if extraction was partial or browser-rendered
+
+If evidence is weak, say so plainly rather than forcing an answer.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `scripts/extract_salesforce_doc.py` | Use to fetch any official Salesforce doc URL; automatically routes `help.salesforce.com` into the dedicated Help extractor and supports browser-rendered extraction for all Salesforce-owned doc hosts |
+| `scripts/extract_help_salesforce.py` | Use directly when targeting `help.salesforce.com` `articleView` URLs; use when the wrapper is not appropriate |
+| `scripts/runtime_bootstrap.py` | Imported by the extraction scripts to resolve the isolated platform-docs-get Python runtime and Playwright browser path; not called directly |
+| `requirements.txt` | Lists Python dependencies (`playwright`, `playwright-stealth`) needed to run the extraction scripts |