@salesforce/afv-skills 1.34.0 → 1.35.0

package/skills/dx-devops-promote/references/cli-commands.md

@@ -0,0 +1,303 @@
+# DevOps Center Promotion CLI Commands Reference
+
+Complete reference for the `sf devops` promotion commands with JSON output schemas and error handling. All commands support `--json` and `--target-org <alias>`. Every command is keyed on **record IDs**, not work item names.
+
+## Command Summary
+
+| Command | Purpose | Required Flags | Async? |
+|---------|---------|---------------|--------|
+| `sf devops promotion validate` | Validate work item promotion to a target stage | `--work-item-id`, `--target-stage-id` | No |
+| `sf devops work-item prepare` | Prepare one work item for promotion | `--work-item-id`, `--target-stage-id` | No |
+| `sf devops work-item combine` | Combine child work items into a parent | `--parent-work-item-id`, `--child-work-item-id`, `--target-stage-id` | No |
+| `sf devops promote` | Promote work item(s) or a stage to a target stage | (`--work-item-id` XOR `--stage-id`), `--target-stage-id`; add `--skip-validation` only if Phase 1 validate passed this session | Yes |
+| `sf devops promotion complete` | Finalize the promotion in the target stage | `--target-stage-id` | No |
+
+**Org authentication** — verify before any command:
+```bash
+sf org display --json
+```
+
+---
+
+## Validate (Mandatory First Step)
+
+Validates whether the specified work item(s) can be promoted to the target stage — checks for VCS and object-permission errors before a promotion is attempted. Requires `--target-stage-id`; repeat `--work-item-id` to validate multiple work items in one call.
+
+```bash
+sf devops promotion validate \
+  --work-item-id 1fkxx0000000001AAA \
+  --target-stage-id 1QVxx0000000001AAA \
+  --target-org myorg \
+  --json
+```
+
+### Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `-i, --work-item-id` | Work item to validate for promotion (required, repeatable) |
+| `-t, --target-stage-id` | Target pipeline stage to validate promotion to (required) |
+| `-o, --target-org` | Target org alias |
+
+### JSON Output Schema (success)
+
+```json
+{
+  "status": 0,
+  "result": {
+    "success": true,
+    "errorType": null,
+    "errorDetails": null,
+    "combineDetails": null,
+    "suggestions": []
+  },
+  "warnings": []
+}
+```
+
+### JSON Output Schema (success, work items share components)
+
+When multiple work items share metadata, validation still succeeds (`success: true`) but returns `combineDetails` and `suggestions` describing whether to combine before promoting:
+
+```json
+{
+  "status": 0,
+  "result": {
+    "success": true,
+    "errorType": null,
+    "errorDetails": null,
+    "combineDetails": {
+      "parentWorkitemId": "1fk000000000001",
+      "childWorkitemsId": ["1fk000000000002"],
+      "sharedComponentsList": {
+        "1fk000000000001": ["MyApexClass", "MyTrigger"],
+        "1fk000000000002": ["MyApexClass"]
+      }
+    },
+    "suggestions": [
+      "The selected work items share one or more components. Choose one of these approaches:",
+      "Option 1 - Combine the work items and promote them as a single unit: ...",
+      "Option 2 - Promote the work items as they are, without combining: ..."
+    ]
+  },
+  "warnings": []
+}
+```
+
+### Interpreting the result
+
+- **Success:** `status == 0` and `.result.success == true`. Proceed.
+- **Shared components:** if `.result.combineDetails` is non-null, the work items share metadata. Use `.result.combineDetails.parentWorkitemId` / `.childWorkitemsId` to drive the combine decision in Phase 2 (see Combine), then promote the parent. This is the authoritative signal for whether to combine — don't guess.
+- **Failure:** a non-zero exit code. The command surfaces an error such as `Validation failed (VCS_ERROR): No pull request exists for the work item on the source branch.`, with `.result.errorType` / `.result.errorDetails` populated in `--json`. STOP — do not prepare/combine/promote. The `VCS_ERROR` case confirms the associated-PR requirement is enforced here.
+
+---
+
+## Prepare
+
+`--target-stage-id` is required (the pipeline stage the work item is being prepared to promote to).
+
+```bash
+sf devops work-item prepare --work-item-id 1fkxx0000000001AAA --target-stage-id 1QVxx0000000001AAA --target-org myorg --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "workItemId": "1fkxx0000000001AAA",
+    "prepared": true
+  }
+}
+```
+
+Idempotent — re-running a prepared work item is a safe no-op.
+
+---
+
+## Combine
+
+Combine one or more child work items into a parent work item so they promote as a single unit. Repeat `--child-work-item-id` once per child.
+
+```bash
+sf devops work-item combine \
+  --parent-work-item-id 1fkxx0000000001AAA \
+  --child-work-item-id 1fkxx0000000002AAA \
+  --child-work-item-id 1fkxx0000000003AAA \
+  --target-stage-id 1QVxx0000000001AAA \
+  --target-org myorg \
+  --json
+```
+
+### Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `--parent-work-item-id` | The primary work item that continues through the pipeline |
+| `--child-work-item-id` | A work item to merge into the parent (repeatable) |
+| `--target-stage-id` | The pipeline stage to promote the combined unit to (required) |
+| `-o, --target-org` | Target org alias |
+
+After combining, promote the **parent** work item ID via `sf devops promote`.
+
+---
+
+## Promote (Async)
+
+Exactly one of `--work-item-id` or `--stage-id` must be provided; they are mutually exclusive. `--target-stage-id` is always required. **Pass `--skip-validation` ONLY when the Phase 1 validate step completed successfully this session for every work item being promoted** — `promote`'s built-in pre-promote validation runs the *same* checks (including the associated-PR requirement) as `sf devops promotion validate`. When that validation already ran this session, skipping avoids a redundant re-run; but if the agent resumed mid-workflow or promotion was invoked without a preceding validate, OMIT the flag so the CLI validates.
+
+### Promote one or more work items
+
+```bash
+sf devops promote \
+  --work-item-id 1fkxx0000000001AAA \
+  --target-stage-id 1QVxx0000000001AAA \
+  --skip-validation \
+  --target-org myorg \
+  --json
+```
+
+Repeat `--work-item-id` per item. For a combined promotion, pass the **parent** work item ID.
+
+### Promote an entire source stage
+
+```bash
+sf devops promote \
+  --stage-id 1QVxx0000000000AAA \
+  --target-stage-id 1QVxx0000000001AAA \
+  --skip-validation \
+  --target-org myorg \
+  --json
+```
+
+### Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `-i, --work-item-id` | Work item to promote (repeatable, mutually exclusive with `--stage-id`) |
+| `-s, --stage-id` | Source stage whose approved work items are promoted (mutually exclusive with `--work-item-id`) |
+| `-t, --target-stage-id` | Destination pipeline stage (required) |
+| `-a, --deploy-all` | Deploy all metadata in the branch, not just changes not yet in the target stage |
+| `-l, --test-level` | Apex test level: `NoTestRun`, `RunSpecifiedTests`, `RunLocalTests`, `RunAllTestsInOrg` |
+| `--tests` | Specific tests to run when `--test-level RunSpecifiedTests` |
+| `--skip-validation` | Skip `promote`'s built-in pre-promote validation. It runs the same checks (including the associated-PR requirement) as `promotion validate`. Pass this ONLY when Phase 1 validate already ran successfully this session; omit it if promotion was invoked without a preceding validate (e.g. mid-workflow resume) so the CLI validates |
+| `-o, --target-org` | Target org alias |
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "promotionId": "0Af000000000001AAA",
+    "sourceStageId": "1QVxx0000000000AAA",
+    "targetStageId": "1QVxx0000000001AAA",
+    "status": "InProgress"
+  }
+}
+```
+
+- Async operation. Capture `.result.promotionId` (some CLI versions use `.result.asyncOperationId`).
+- Poll the returned identifier separately to confirm completion — do NOT busy-wait here.
+- After the deploy completes, run `sf devops promotion complete` to finalize.
+
+---
+
+## Promotion Complete
+
+Finalize the promotion — advances the promoted work items in the target stage. Run after the promote deploy succeeds. `--target-stage-id` is required (the same target stage the work items were promoted to).
+
+```bash
+sf devops promotion complete --target-stage-id 1QVxx0000000001AAA --target-org myorg --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "completed": true,
+    "targetStageId": "1QVxx0000000001AAA"
+  }
+}
+```
+
+---
+
+## Error Handling
+
+**Work item not found:**
+```json
+{ "status": 1, "name": "NOT_FOUND", "message": "Work item does not exist or is not accessible", "exitCode": 1 }
+```
+
+**Not prepared before promote:**
+```json
+{ "status": 1, "name": "NOT_PREPARED", "message": "Work item has not been prepared for promotion", "exitCode": 1 }
+```
+
+**Missing target stage:**
+```json
+{ "status": 1, "name": "MissingRequiredFlag", "message": "Missing required flag --target-stage-id", "exitCode": 1 }
+```
+
+**Conflict on deploy:**
+```json
+{ "status": 1, "name": "DEPLOY_CONFLICT", "message": "Metadata conflict detected during deployment", "exitCode": 1 }
+```
+
+**Authentication failure:**
+```json
+{ "status": 1, "name": "NoOrgFound", "message": "No org configuration found for target-org. Run 'sf org login web' to authenticate.", "exitCode": 1 }
+```
+
+---
+
+## Parsing Async Promotion IDs
+
+```bash
+# Promote and capture the promotion ID for status polling.
+# --skip-validation is shown here because this snippet assumes Phase 1 validate
+# already passed this session; OMIT it if promotion is invoked without a
+# preceding validate (e.g. a mid-workflow resume).
+PROMOTION_ID=$(sf devops promote \
+  --work-item-id 1fkxx0000000001AAA \
+  --target-stage-id 1QVxx0000000001AAA \
+  --skip-validation \
+  --target-org myorg \
+  --json | jq -r '.result.promotionId // .result.asyncOperationId')
+
+echo "Promotion initiated. Promotion ID: $PROMOTION_ID"
+# Poll this ID separately, then run: sf devops promotion complete --target-stage-id 1QVxx0000000001AAA --target-org myorg --json
+```
+
+---
+
+## Resolving Names to IDs
+
+Promotion commands need record IDs. Resolve a project name and work item subject/name to IDs first:
+
+```bash
+# List projects to resolve a project name to an ID
+# (project list returns .result.projects[] with capitalized .Id / .Name)
+sf devops project list --json | jq -r '.result.projects[] | "\(.Id): \(.Name)"'
+
+# Resolve a work item subject to its ID
+# (work-item list returns .result.workItems[] with .id / .subject)
+sf devops work-item list --project-id <project-id> --json | \
+  jq -r '.result.workItems[] | select(.subject == "<subject>") | .id'
+```
+
+---
+
+## Authentication Requirements
+
+All promotion commands require:
+
+1. **Authenticated org**: `sf org login web` or JWT auth (for CI)
+2. **DevOps Center enabled**: org must have DOCe provisioned
+3. **Promotion permissions**: user/service account must be able to promote in the target pipeline
+
+Auth is the caller's responsibility — these skills contain no auth logic. In CI, use a JWT-authenticated service-account alias with least-privilege scopes.

package/skills/experience-lwc-base-components-integrate/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: experience-lwc-base-components-integrate
+description: "Pick the right Lightning Base Component (`lightning-*`) for a given UI task, retrieve its full API (props, methods, events, slots) from the bundled per-component reference, and wire it into an LWC (LWC `.html`, `.js`, and `.css` files) without breaking SLDS. Use this skill when users say \"I need a Lightning modal / datatable / combobox / record form\", ask which `lightning-*` component fits a use case, want a shortlist of LBC candidates, are about to hand-roll a UI that a base component already provides, or are editing an LWC bundle's `.html` / `.js` / `.css` and need to select or wire a base component. Also triggers on \"Lightning base component\", \"LBC\", \"lightning-combobox\", \"lightning-datatable\", \"use `lightning-` tag\". DO NOT TRIGGER for applying SLDS design tokens, blueprints, or styling guidance in general — that is `design-systems-slds-apply`; this skill only selects and wires `lightning-*` base components."
+metadata:
+  version: "1.0"
+  relatedSkills:
+    - design-systems-slds-apply
+---
+<!-- adk-managed-skill -->
+
+# Using Lightning Base Components
+
+Lightning Base Components (LBC) are the `lightning-*` web components shipped
+by Salesforce. This skill routes an agent through the right decision sequence
+so the final component choice is **as specific as possible** and backed by
+real API docs — not a hand-rolled reimplementation of something that already
+exists.
+
+## When to Use This Skill
+
+- User describes a UI need ("searchable dropdown", "record edit form",
+  "modal with footer") and asks which `lightning-*` component fits.
+- User is about to build a primitive (button group, combobox, toast) and
+  should be using LBC instead.
+- User asks you to review LWC markup for LBC-related issues — specifically
+  overriding SLDS classes or restyling LBC internals.
+- User needs the authoritative props/events/slots for a specific
+  `lightning-*` tag.
+
+## Prerequisites
+
+- Knowledge of which LBC namespace your org uses (`lightning` is the default
+  public namespace; some platforms expose `lightning-community` or others —
+  the user's meta files will clarify).
+- The skill ships authoritative API docs for every Lightning Base Component
+  in [references/lightning-components.md](references/lightning-components.md).
+  Each component is a `# Component API Structure` block; grep for
+  `**Name:** <camelCaseName>` (e.g. `**Name:** datatable`) to jump to its
+  Properties / Methods / Events / Slots. Read this rather than relying on
+  cached knowledge — LBC evolves and the reference is the source of truth.
+
+
+## Workflow
+
+### Step 1 — Read the **entire** component index first
+
+Open [lightning-component-index.md](references/lightning-component-index.md)
+and scan **all** entries before making any selection. This is non-negotiable:
+LBC's value comes from picking the most specialized component, and skipping
+the scan leads to reinventing compound widgets out of primitives.
+
+As you scan, compile a **candidate list** — every component whose description
+touches any aspect of the use case. Do not filter or rank yet.
+
+### Step 2 — Narrow to the most specific fit per feature
+
+Once the scan is complete:
+
+- For each feature in the use case, select the **most specific** component
+  that covers it. Prefer a specialized compound (`lightning-record-form`,
+  `lightning-tabset`, `lightning-datatable`) over a generic primitive
+  (`lightning-input`, `lightning-button`) when the specialized one covers
+  the scenario end-to-end.
+- Avoid duplication: if `lightning-record-form` already renders fields for a
+  record, do not pair it with `lightning-input-field` unless you're
+  explicitly overriding behavior.
+
+### Step 3 — Share the shortlist and confirm
+
+Present the final shortlist to the developer with a one-line rationale per
+component. Wait for explicit confirmation before pulling full API docs. This
+prevents the agent from burning context on components the developer has
+already mentally ruled out.
+
+### Step 4 — Retrieve full API docs
+
+Once confirmed, use the bundled helper to pull the exact API blocks — this
+avoids ad-hoc grepping across a large reference:
+
+```bash
+scripts/extract-component-docs.sh <camelCaseName> [<camelCaseName>...]
+```
+
+Convert `lightning-<foo>` tags to camelCase (no `lightning-` prefix):
+
+- `lightning-datatable` → `datatable`
+- `lightning-record-edit-form` → `recordEditForm`
+- `lightning-button-icon` → `buttonIcon`
+
+Each returned block has the same shape: **Basic Information** (tag, namespace,
+type), **Properties** (name, type, default, description), **Methods**,
+**Events**, **Slots**, and (where applicable) usage notes. This skill is about
+**picking** the components; the bundled reference is about **wiring** them.
+
+### Step 5 — Produce integration guidance
+
+Using the per-component reference, walk the developer through:
+
+- The exact `<lightning-...>` tag and required attributes.
+- Which events to bind (`onchange`, `oncommit`, `onsuccess`, …) and what
+  the event payload contains.
+- Any slots to fill (headers, footers, custom content).
+- Known constraints from the component docs (e.g. `lightning-record-form`
+  requires `object-api-name` and `record-id` for edit/view modes).
+
+### Step 6 — Respect LBC styling rules
+
+Do not override SLDS classes on LBC internals. See
+[lbc-expert-guidance.md](references/lbc-expert-guidance.md) for specifics.
+Common issues:
+
+- Targeting `.slds-button` or `.slds-input` in the host component's CSS to
+  restyle an LBC — LBC ships inside a shadow root, so these selectors
+  either leak into sibling components or get stripped entirely. Use the
+  component's documented styling hooks (`--sds-c-button-*`, etc.) instead.
+- Wrapping an LBC just to mutate its internal markup. You can't — the
+  markup is hidden behind the shadow root. If the component doesn't expose
+  the slot/prop you need, that's a platform-level gap, not a restyling job.
+
+
+## Examples
+
+### Example — "I need a multi-select combobox with typeahead"
+
+1. Scan the component index end-to-end.
+2. Candidate list includes: `lightning-combobox`, `lightning-dual-listbox`,
+   `lightning-record-picker`.
+3. Shortlist: `lightning-dual-listbox` (the documented multi-select base
+   component). Rule out `lightning-combobox` — its documented API is
+   single-select; it has no `type="multi"` and no multi-select mode.
+   Flag that `lightning-record-picker` only fits if the values are record IDs.
+4. Developer confirms `lightning-dual-listbox`.
+5. Run `scripts/extract-component-docs.sh dualListbox`.
+6. Return the `options`, `value`, `onchange` payload, and required label
+   props from the block's Properties / Events sections.
+
+### Example — "I'm going to write my own modal"
+
+1. Scan finds `lightning-modal`, `lightning-modal-body`,
+   `lightning-modal-footer`, `lightning-modal-header`.
+2. Shortlist is the 4 modal components.
+3. Confirm.
+4. Run `scripts/extract-component-docs.sh modal modalHeader modalBody modalFooter`
+   → full modal API (how to extend `LightningModal`, the static `.open()`
+   pattern, slotting the header/body/footer).
+5. Steer the developer away from rolling their own dialog.
+
+
+## Verification Checklist
+
+- [ ] The full component index was scanned before any selection (no
+      keyword-search shortcutting).
+- [ ] Candidate list included every component that touches the use case.
+- [ ] Final shortlist selects the **most specific** component per feature.
+- [ ] Developer confirmed the shortlist before the bundled component
+      reference was opened.
+- [ ] Integration guidance cites props / events / slots from the real API
+      docs (not inferred).
+- [ ] No suggestions to restyle LBC by overriding SLDS classes.
+
+
+## Troubleshooting
+
+- **Grep for `**Name:** <name>` returns no match** — name is wrong, or the
+  reference uses a different camelCase. Double-check against the component
+  index (`lightning-record-form` → `recordForm`,
+  `lightning-record-view-form` → `recordViewForm`,
+  `lightning-button-icon` → `buttonIcon`).
+- **Proposed component doesn't have the prop you expected** — trust the
+  real API doc over memory. LBC evolves; cached knowledge lies.
+- **Developer resists the shortlist** — don't skip Step 4. Still retrieve
+  the docs for the developer's preferred choice so they see the actual
+  trade-offs.
+- **Developer wants to restyle LBC internals** — redirect to styling hooks
+  (see the LBC Expert reference). Refusing shadow DOM penetration is the
+  correct answer.

package/skills/experience-lwc-base-components-integrate/references/lbc-expert-guidance.md

@@ -0,0 +1,127 @@
+# Lightning Base Component Styling Guidelines
+
+## Description
+
+Styling guidelines for Lightning Web Components that consume Lightning Base Components: when component CSS layers custom styles on top of `lightning-*` components, certain SLDS-class usage patterns break the SLDS contract and must be rewritten to use component-owned custom classes.
+
+## The core rule
+
+Never target an SLDS class (`.slds-*`) in a component's CSS, either directly or as part of a compound selector. SLDS classes are owned by SLDS and may change their internal styling at any time; overriding them invalidates the SLDS guarantee.
+
+## Scope
+
+These guidelines apply when:
+
+- The LWC uses one or more `lightning-*` Base Components, AND
+- The component CSS contains selectors that include `.slds-*` class names.
+
+## Fix pattern
+
+Replace direct or compound SLDS-class selectors with component-owned custom classes. The fix always touches **both** the HTML template (to add the custom class) and the CSS (to retarget the selector).
+
+### Example — overriding SLDS class properties directly
+
+**Before**
+
+CSS:
+
+```css
+.slds-button {
+  background: pink;
+}
+
+.slds-component_active .slds-combobox {
+  display: block;
+}
+```
+
+HTML:
+
+```html
+<template>
+  <button class="slds-button">Click me</button>
+  <div class="slds-component_active slds-combobox">I'm going to display something based on state</div>
+</template>
+```
+
+**Problem:** the CSS overrides SLDS styles directly. This invalidates the SLDS contract and breaks under SLDS internal changes.
+
+**After**
+
+HTML — add custom classes alongside the existing SLDS classes:
+
+```html
+<template>
+  <button class="slds-button primary-button">Click me</button>
+  <div class="slds-component_active slds-combobox active-display">I'm going to display something based on state</div>
+</template>
+```
+
+CSS — target the custom classes, with the SLDS classes removed from the selectors entirely:
+
+```css
+.primary-button {
+  background: pink;
+}
+
+.active-display {
+  display: block;
+}
+```
+
+### Key properties of the fix
+
+- HTML: introduce a new custom class name (e.g. `primary-button`, `active-display`) on the element that needs styling.
+- CSS: rewrite the selector to target the new custom class. The SLDS class is **completely removed** from the selector.
+- Markup structure (tags, nesting, attributes other than `class`) is never changed.
+
+## How to apply
+
+For each LWC that uses a `lightning-*` Base Component, scan the CSS for selectors that contain `.slds-*` (direct or compound). For each occurrence, produce a paired HTML+CSS edit:
+
+1. **HTML** — add a new custom class (kebab-case, component-scoped name) to the element being styled, alongside the existing SLDS class. Do not change tags, nesting, or any non-`class` attribute.
+2. **CSS** — rewrite the selector to target the new custom class only. Remove the `.slds-*` segment from the selector entirely.
+
+Produce one fix entry per violation with: file + line number for the HTML edit, file + line number for the CSS edit, and the corrected selector. Apply the same custom-class naming convention consistently across all violations in the same component.
+
+### Example: component with SLDS class in CSS selector
+
+**Component HTML:**
+
+```html
+<template>
+  <div class="fooDiv">
+    <button class="slds-button">Click me</button>
+  </div>
+</template>
+```
+
+**Component CSS:**
+
+```css
+.fooDiv .slds-button {
+  background-color: red;
+}
+```
+
+**Issue:** The CSS selector `.fooDiv .slds-button` targets the SLDS class directly. This overrides SLDS internal styles and breaks the SLDS contract.
+
+**Fix:**
+
+Add a custom class to the `button` element on line 3 of the HTML:
+
+```html
+<template>
+  <div class="fooDiv">
+    <button class="slds-button custom-button">Click me</button>
+  </div>
+</template>
+```
+
+Retarget the CSS selector to the custom class:
+
+```css
+.custom-button {
+  background-color: red;
+}
+```