@salesforce/afv-skills 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/analyzing-test-failures/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: analyzing-test-failures
+description: "Parses a DevOps Center test-failure or Code Analyzer violation payload and explains it in plain language — failure category, offending file/class/method/line, rule violated, and fix direction — then gives prioritized test-improvement suggestions (distinguishing test-code from production-code fixes). Pure reasoning: no system calls or code authoring. TRIGGER when: a test run failed and the user wants root cause; a quality gate failure needs explaining; Code Analyzer violations need translating to plain language; the user shares a failure payload and asks how to address it; tests keep failing and the user wants suggestions; or the user wants to close coverage gaps, strengthen assertions, or fix flaky/weak tests. DO NOT TRIGGER when: the user wants fix code written (use generating-apex) or new test classes authored (use generating-apex-test)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# analyzing-test-failures
+
+**Type:** Pure reasoning — no system calls, no code authoring.
+
+**What it does:** Parses a test failure or Code Analyzer violation payload and produces a plain-language explanation, then follows up with concrete, prioritized improvement suggestions per failed test — including whether each fix belongs in the test or in production code. Never exposes raw JSON, stack traces, or API error bodies to the user.
+
+---
+
+## Prerequisites
+
+If you need to fetch the failure payload yourself rather than receiving it, load `checking-devops-prerequisites` first, then use `polling-test-results` to obtain the execution result. If the payload is already in context, no prerequisites are needed — this is pure reasoning.
+
+---
+
+## Inputs
+
+- JSON failure payload provided by the `polling-test-results` skill, or pasted directly into context from a test run or Code Analyzer execution. Specifically required per failed test:
+  - Test method name
+  - Failure message (the assertion error or exception text)
+  - Failure category (assertion failure, unhandled exception, timeout, compile error)
+
+---
+
+## Empty-org / no-data case
+
+If the payload contains no failures or violations, report that clearly (e.g. "No failures found in the provided execution results.") and stop. Do NOT fabricate failures, violations, or improvement suggestions when none are present.
+
+---
+
+## Reasoning steps
+
+1. Determine the failure category:
+
+   | Category | Description |
+   |---|---|
+   | **Assertion failure** | A test assertion failed (expected vs actual mismatch) |
+   | **Exception** | An unhandled exception was thrown |
+   | **Code Analyzer violation** | A static analysis rule was violated (e.g. `ApexCRUDViolation`, `ApexSharingViolations`) |
+   | **Timeout** | Test exceeded execution time limit |
+   | **Compile error** | Class failed to compile |
+
+2. For each failure, extract and translate to plain language:
+   - Offending file and class name
+   - Method name
+   - Line number
+   - What rule or assertion was violated, in plain language
+   - Suggested fix direction (without writing code)
+
+3. Group failures by category if more than one.
+
+---
+
+## Output format
+
+```text
+Test failure summary:
+
+<N> failure(s) found:
+
+1. [<Category>] `<ClassName>.cls` — `<methodName>()` at line <N>
+   What happened: <plain-language description>
+   Rule violated: <ruleName or assertion description>
+   Fix direction: <plain-language suggestion>
+
+2. [<Category>] `<ClassName2>.cls` — `<methodName2>()` at line <N>
+   ...
+```
+
+---
+
+## Code Analyzer violations
+
+For violations, always include:
+- The rule name translated to plain English (e.g. "ApexCRUDViolation" → "A SOQL query was made without checking object-level permissions first")
+- The exact line number
+- The fix direction (e.g. "Add a `Schema.sObjectType.Account.isAccessible()` check before the query")
+
+---
+
+## Plain-language rule
+
+Never paste raw stack traces, JSON payloads, or internal Salesforce error codes into the output. Always translate to file name, method, line, and plain description.
+
+---
+
+## Suggesting improvements
+
+Invoke this section **after test execution completes with failures**, not on static source code. The failure message is the primary signal — it describes what the test expected vs. what actually happened, which directly informs what the test needs to handle better.
+
+### 1 — Read each failure message
+
+For each failed test in the execution result, extract:
+- Test method name
+- Failure message (the assertion error or exception message)
+- Failure category (assertion failure, unhandled exception, timeout, compile error)
+
+### 2 — Infer what the test is not handling
+
+Reason over the failure message to identify the root cause pattern:
+
+| Failure pattern | Improvement suggestion |
+|---|---|
+| `NullPointerException` | The test is not handling null input — add a null check or a test setup that ensures the data exists |
+| `Assertion failed: expected X but was Y` | The expected value in the assertion is wrong or the test data setup does not produce the right state |
+| `List has no rows for assignment` | The test is querying for data that doesn't exist — test setup is incomplete |
+| `System.LimitException: Too many SOQL queries` | The test is hitting governor limits — the code under test or test setup is making too many queries |
+| `Insufficient access rights on cross-reference id` | The test user lacks the required permissions — the test needs to run as a user with appropriate profile/permission set |
+| `DML currently not allowed` | The test is performing DML inside a method called from a context that doesn't allow it |
+| Code Analyzer violation message | The production code violates a specific rule — the test exposed it but the fix is in the production code, not the test |
+
+### 3 — Produce actionable suggestions
+
+For each failure, describe in plain language:
+- What the failure reveals about what the test is not handling
+- What specifically should be added or changed to make the test robust
+- Whether the fix is in the **test** (assertion, setup, permissions) or in the **production code** (the test is correct but the code under test is broken)
+
+Do not rewrite the test. Only describe what needs to change and why.
+
+### Output format for improvements
+
+```text
+Test improvement suggestions based on execution results:
+
+`<testMethodName>()` — [Assertion Failure / Exception / etc.]
+Failure: "<failure message>"
+What this reveals: <plain-language explanation>
+Suggestion: <specific, actionable recommendation>
+Fix location: Test | Production code
+
+`<testMethodName2>()` — [NullPointerException]
+Failure: "Attempt to de-reference a null object"
+What this reveals: The test is calling the method without setting up the required input data
+Suggestion: Add test data setup for <object/field> before calling the method
+Fix location: Test
+
+Overall: <N> improvement(s) across <M> failed test(s).
+```
+
+### Test fix vs. production-code fix
+
+Suggestions flagged as **Fix location: Production code** indicate a code defect exposed by the test — the test logic itself is sound. These should not block suite promotion on the grounds of test quality; they should be tracked separately as production defects.
+
+Suggestions flagged as **Fix location: Test** indicate the test needs to be hardened — missing setup, wrong assertions, inadequate coverage of edge cases (null inputs, bulk record volumes, mixed permission contexts, governor-limit boundaries).
+
+---
+
+## Related skills
+
+- **`polling-test-results`** — obtains the failure payload that feeds into this skill.
+- **`creating-fix-work-item`** — use to create a tracked fix item from the analysis output or to track an approved improvement suggestion as a work item once the user decides to act on it.

package/skills/building-sf-integrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-sf-integrations
-description: "Salesforce integration architecture and runtime plumbing with 120-point scoring. Use this skill to set up Named Credentials, External Credentials, External Services, REST/SOAP callout patterns, Platform Events, and Change Data Capture. TRIGGER when: user sets up Named Credentials, External Services, REST/SOAP callouts, Platform Events, CDC, or touches .namedCredential-meta.xml files. DO NOT TRIGGER when: Connected App/OAuth config (use configuring-connected-apps), Apex-only logic (use generating-apex), or data import/export (use handling-sf-data)."
+description: "Salesforce integration architecture and runtime plumbing with 120-point scoring. Use this skill to set up Named Credentials, External Credentials, External Services, REST/SOAP callout patterns, Platform Events, and Change Data Capture. TRIGGER when: user sets up Named Credentials, External Services, REST/SOAP callouts, Platform Events, CDC, or touches .namedCredential-meta.xml files. DO NOT TRIGGER when: Connected App/OAuth config (use configuring-connected-apps), Apex-only logic (use generating-apex), data import/export (use handling-sf-data), or CDC channel-membership metadata such as PlatformEventChannel, PlatformEventChannelMember, or EnrichedField (use managing-cdc-enablement)."
 metadata:
   version: "1.1"
 ---

package/skills/checking-devops-prerequisites/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: checking-devops-prerequisites
+description: "Validate the environment before any DevOps Center pipeline testing action: confirms an authenticated Salesforce org, the Agentforce DX plugin, an authenticated DevOps Center org, and an identified pipeline (and optionally a pipeline stage). Use this FIRST, internally, from any DevOps testing skill (running a test suite, polling results, syncing tests, configuring or retriggering a quality gate, assigning/mapping suites, creating fix work items, recommending tests, explaining coverage, analyzing failures). TRIGGER when another DevOps testing skill needs to confirm org/pipeline context before a query or system call. DO NOT TRIGGER for non-DevOps-Center work."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Checking DevOps Prerequisites
+
+Shared gate for every DevOps Center testing skill. Run these checks **before** any query or system call. On any failure, surface the plain-language message and stop until the user resolves it — never proceed to a write with an unverified environment.
+
+> **API version:** All DevOps testing system calls target Salesforce API **v67.0** (minimum required).
+
+**Important:** All DevOps Center data (pipelines, stages, test suites, executions) lives in the Salesforce org — NOT in the local repository. Never search the filesystem for pipeline configuration. Always query the org using `sf data query` or `sf api request rest`.
+
+## How other skills use this
+
+Every DevOps testing skill loads this skill first and runs Prerequisites 1–4 in order. Prerequisite 5 (stage) is run **only** when the calling skill operates on a specific pipeline stage (running/retriggering a suite, syncing, configuring a gate, mapping a suite). The calling skill passes back the resolved `doce-org-alias`, `pipelineId`, and (when applicable) `stageId` to use in its own commands.
+
+Resolve the **DevOps Center org alias** without asking the user unless genuinely ambiguous:
+1. If the user named an org alias in their message, use it.
+2. Otherwise, use the default org (`sf org display --json`, no `--target-org`).
+3. Only if the default org has no `DevopsPipeline` records (Prereq 4 fails), ask: "Which org alias is your DevOps Center org?"
+
+---
+
+## Prerequisite 1 — Salesforce org: active login
+
+```bash
+sf org list --json
+```
+
+Look for at least one entry in `result.nonScratchOrgs`, `result.scratchOrgs`, or `result.sandboxes` with `"connectedStatus": "Connected"`.
+
+- **Pass:** at least one org is Connected
+- **Fail:** no orgs listed, or all show a non-connected status
+
+**On fail:** "No authenticated Salesforce org found. Run `sf org login web --alias <your-alias>` in your terminal, then come back."
+
+---
+
+## Prerequisite 2 — Agentforce DX plugin installed
+
+```bash
+sf plugins --json
+```
+
+Look for a plugin entry whose `name` contains `plugin-agent`, `agentforce`, or `einstein` (case-insensitive).
+
+- **Pass:** plugin found
+- **Fail:** no matching entry
+
+**On fail:** "The Agentforce DX Plugin is not installed. Run `sf plugins install @salesforce/plugin-agent`, then restart the IDE and try again."
+
+---
+
+## Prerequisite 3 — DevOps Center org authenticated
+
+```bash
+sf org display --target-org <doce-org-alias> --json
+```
+
+Check that `"connectedStatus"` is `"Connected"`.
+
+- **Pass:** Connected
+- **Fail:** expired session or error
+
+**On fail:** "Your DevOps Center org session has expired. Run `sf org login web --alias <doce-org-alias>` to re-authenticate."
+
+---
+
+## Prerequisite 4 — Pipeline identified
+
+```bash
+sf data query \
+  --query "SELECT Id, Name, CreatedDate FROM DevopsPipeline ORDER BY Name ASC" \
+  --target-org <doce-org-alias> \
+  --json
+```
+
+- **Pass (exactly one):** use it automatically — do NOT ask.
+- **Pass (multiple):** if the user already named a pipeline, match by name. Otherwise display a numbered list and ask:
+  ```text
+  Found <N> pipelines:
+  1. <Name>
+  2. <Name>
+  Which pipeline would you like to work with?
+  ```
+- **Fail (no records):** "No DevOps Center pipeline found. Create a project and pipeline in DevOps Center before using the DevOps Testing Skills."
+- **Fail (unsupported object):** "DevOps Center does not appear to be installed on `<doce-org-alias>`. Check that you're pointing at the correct org."
+
+---
+
+## Prerequisite 5 — Pipeline stage identified (conditional)
+
+Run **only** when the calling skill operates on a specific stage.
+
+If the user's message already names a stage (e.g. "Integration", "Staging", "Production"), use that name directly — do NOT ask again. Look up its Id:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' AND Name = '<stageName>'" \
+  --target-org <doce-org-alias> --json
+```
+
+Only if no stage is mentioned, fetch the full list and ask which one:
+
+```bash
+sf data query \
+  --query "SELECT Id, Name FROM DevopsPipelineStage WHERE DevopsPipelineId = '<pipelineId>' ORDER BY Name ASC" \
+  --target-org <doce-org-alias> --json
+```
+
+Then ask: "Which pipeline stage are we working with?" — do NOT ask for an org alias; stages are resolved by name from the pipeline.
+
+- **Pass:** stage Id and Name confirmed
+- **Deferred:** not required until a calling skill needs it
+
+---
+
+## Error Handling
+
+| Error condition | Response |
+|---|---|
+| `sf org list` fails entirely | "Could not reach the Salesforce CLI. Make sure `sf` is installed and on your PATH." |
+| `sf org display` returns auth error | Surface plain-language re-auth instructions. Do not expose the raw error. |
+| `DevopsPipeline` query fails with 5xx | "The DevOps Center org is returning a server error. Try again in a few minutes." |
+| Any check throws unexpectedly | "Something went wrong checking prerequisites. Error: [plain summary]. Let's try again — or resolve it manually and let me know when ready." |
+
+Never expose raw API errors, stack traces, or JSON error payloads to the user.
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| `DevopsPipeline` query returns empty | DevOps Center not installed on the target org, or wrong org alias — ask the user to verify |
+| `DevopsWorkItem` sObject not supported | Use `WorkItem` (no namespace) — the correct API name for this org version |
+| Review trigger is pipeline-level, not stage-level | Query `DevopsPipelineStageTrigger` where `TriggerType = 'Review'` and `RelatedRecordId = <pipelineId>` |
+| Connect API `testSuites` returns empty with `?stageId=` | Use `?triggerId=<reviewTriggerId>` — `stageId` only works for stage-level triggers |
+| `sf plugins` doesn't match `agentforce` | The installed plugin is `@salesforce/plugin-agent` — match on `plugin-agent` too |