@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/experience-lwc-design-generate/scripts/detect-project-tools.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Reports which of the Phase-4 lint/format/compile tools are configured
+# in the target project. Emits one `<tool>=yes|no` line per checked tool
+# on stdout so the caller can gate each Phase-4 substep deterministically
+# instead of parsing prose.
+#
+# Detected tools:
+#   eslint       — .eslintrc.* / eslint.config.* / package.json `eslintConfig`
+#   prettier     — .prettierrc* / prettier.config.* / package.json `prettier`
+#   cursor-rules — .cursor/rules/ or .cursorrules
+#   lwc-compiler — sfdx-project.json or @lwc/compiler in package.json dependencies
+#
+# Usage:
+#   <skill_dir>/scripts/detect-project-tools.sh [<projectRoot>]
+#
+# `<projectRoot>` defaults to the current working directory.
+#
+# Exit codes:
+#   0 — detection completed (output on stdout is authoritative)
+#   2 — usage error
+
+set -euo pipefail
+
+if [ "$#" -gt 1 ]; then
+  echo "usage: $0 [<projectRoot>]" >&2
+  exit 2
+fi
+
+root="${1:-.}"
+
+if [ ! -d "$root" ]; then
+  echo "detect-project-tools: project root \`$root\` does not exist" >&2
+  exit 2
+fi
+
+python3 - "$root" <<'PY'
+import json
+import os
+import sys
+from pathlib import Path
+
+root = Path(sys.argv[1]).resolve()
+
+def has_any(patterns):
+    for p in patterns:
+        # Interpret `*` as a shell-style glob relative to `root`.
+        matches = list(root.glob(p))
+        if matches:
+            return True
+    return False
+
+def has_pkg_key(key):
+    pkg = root / "package.json"
+    if not pkg.is_file():
+        return False
+    try:
+        data = json.loads(pkg.read_text(encoding="utf-8"))
+    except Exception:
+        return False
+    if key in data:
+        return True
+    deps = {}
+    for section in ("dependencies", "devDependencies", "peerDependencies"):
+        d = data.get(section) or {}
+        if isinstance(d, dict):
+            deps.update(d)
+    return key in deps
+
+def yn(cond):
+    return "yes" if cond else "no"
+
+eslint = has_any([
+    ".eslintrc",
+    ".eslintrc.*",
+    "eslint.config.*",
+]) or has_pkg_key("eslintConfig")
+
+prettier = has_any([
+    ".prettierrc",
+    ".prettierrc.*",
+    "prettier.config.*",
+]) or has_pkg_key("prettier")
+
+cursor_rules = has_any([
+    ".cursor/rules",
+    ".cursorrules",
+])
+
+lwc_compiler = has_any([
+    "sfdx-project.json",
+]) or has_pkg_key("@lwc/compiler")
+
+print(f"eslint={yn(eslint)}")
+print(f"prettier={yn(prettier)}")
+print(f"cursor-rules={yn(cursor_rules)}")
+print(f"lwc-compiler={yn(lwc_compiler)}")
+PY

package/skills/experience-lwc-runtime-observe/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: experience-lwc-runtime-observe
+description: "Use when running Salesforce Lightning Preview for an app or a single LWC component to extract the runtime DOM for inspection. TRIGGER when the user says \"preview an LWC locally\", \"run sf lightning dev\", \"launch Local Dev\", \"inspect a component's shadow DOM at runtime\", \"grab rendered HTML from a live preview\", \"troubleshoot what actually renders versus the template\", \"set up Salesforce Live Preview plugin\", \"lightning preview\", \"local dev server\", or \"extract runtime DOM\". DO NOT TRIGGER when the user is authoring or editing LWC source code (use experience-lwc-generate) or reviewing component code statically without running it."
+metadata:
+  version: "1.0"
+  cliTools:
+    - tool: ["python3"]
+      semver: ">=3.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - experience-lwc-generate
+---
+<!-- adk-managed-skill -->
+
+# Previewing LWC Runtime — Local Dev + DOM Inspection
+
+Guides the agent through two sequential jobs that typically run together:
+
+1. **Start a Lightning Preview session** with the Salesforce CLI so an LWC app
+   or component renders in a local dev environment.
+2. **Navigate to that preview URL and extract the runtime DOM subtree** so the
+   agent (or user) can reason about what actually rendered.
+
+Preview is the prerequisite for DOM inspection. Keep them in this order.
+
+## When to Use This Skill
+
+- The user wants to preview an LWC app or component locally before deploying
+  (`sf lightning dev app` / `sf lightning dev component`).
+- The user wants the rendered HTML subtree for a specific component at runtime
+  — for a diff, a screenshot pipeline, or to reason about shadow DOM.
+- The user asks why the template content "isn't in the DOM" — almost always
+  a shadow-DOM misunderstanding handled in Step 2.
+
+## Prerequisites
+
+- Salesforce CLI (`sf`) installed. Check with `sf version`.
+- `@salesforce/plugin-lightning-dev` installed. Check with `sf plugins`.
+- An authenticated org (`sf org list` shows at least one connected org).
+- For DOM extraction: browser automation available in the agent harness
+  (Playwright, Puppeteer, Chrome DevTools Protocol — whatever is wired up).
+
+---
+
+## Step 1 — Start the Lightning Preview
+
+Ask the user (or infer from the request) whether the scope is **app** or
+**component**.
+
+### 1a. Verify the toolchain
+
+Ask the user for (or infer from the request) the org alias the preview
+should target. Run the bundled verification script with that alias and
+surface any error it emits — do not re-invoke `sf version` /
+`sf plugins` / `sf org display` in prose. The script checks CLI
+presence, `@salesforce/plugin-lightning-dev` installation, and that the
+specific target alias is authenticated and Connected, and exits nonzero
+with an actionable message on failure:
+
+```bash
+"<skill_dir>/scripts/verify-toolchain.sh" <orgAlias>
+```
+
+If it reports that the target alias is not authenticated or not
+Connected, direct the user to
+[Enable Local Dev](https://developer.salesforce.com/docs/platform/lwc/guide/get-started-test-components.html#enable-local-dev)
+and have them run `sf org login web --alias <orgAlias>`, then re-run the
+verification script before proceeding.
+
+### 1b. Read the subcommand's flags
+
+```bash
+# For app scope
+sf lightning dev app --help
+
+# For component scope
+sf lightning dev component --help
+```
+
+Note required vs optional flags. If a required flag is ambiguous, ask the user
+before running.
+
+### 1c. Launch the preview
+
+Prefix every preview command with `OPEN_BROWSER=false` — the CLI opens a
+browser window by default, which we do **not** want when an agent is driving.
+(This env var is undocumented in `--help`; rely on it unless the user
+explicitly asks for a browser window.)
+
+| Scope       | Command                                                                               |
+|-------------|---------------------------------------------------------------------------------------|
+| `app`       | `OPEN_BROWSER=false sf lightning dev app -o <orgAlias> -n <appName> -t desktop`       |
+| `component` | `OPEN_BROWSER=false sf lightning dev component -o <orgAlias> -n <componentName>`      |
+
+When the preview is up, capture the URL and log it in exactly this format:
+
+```text
+Lightning Preview running at URL: <URL>
+```
+
+If any sub-step fails, stop and surface the error to the user — don't try to
+paper over auth or plugin-install problems.
+
+---
+
+## Step 2 — Extract the Runtime DOM
+
+Only run this step once Step 1 has produced a live preview URL.
+
+### 2a. Get an authenticated front-door URL — **without surfacing the token to agent context**
+
+The front-door URL returned by `sf org open --url-only --json` contains a
+short-lived OTP that authenticates the session. **Never run `sf org open`
+directly — its output would land in the agent tool-output stream and leak
+an auth token into the transcript, violating agent-safety standard S1.**
+The bundled helper is the *only* supported way to obtain the URL: it runs
+`sf org open` internally with stdout redirected into a `chmod 600` tempfile
+and stderr suppressed, so no URL fragment or token substring ever reaches
+agent context.
+
+Instead, use the bundled helper script, which writes the URL to a
+`chmod 600` tempfile and prints only `export` assignments (no token
+material). Capture the helper output first so a nonzero exit status
+aborts the caller — `eval "$(...)"` alone masks failures, letting the
+agent proceed with an unset `$FRONTDOOR_URL_FILE`:
+
+```bash
+frontdoor_env="$("<skill_dir>/scripts/open-frontdoor.sh" <orgAlias> <previewUrl>)" || exit 1
+eval "$frontdoor_env"
+```
+
+The helper suppresses `sf` and `python3` stderr as well as stdout, so
+partial URLs and progress noise never reach the agent transcript.
+
+The browser driver must:
+1. Read the URL from `$FRONTDOOR_URL_FILE`.
+2. Navigate to it to establish a session.
+3. Delete the tempfile immediately after use.
+4. **Never `cat` or otherwise echo the file contents.**
+
+**OTP tokens expire fast.** Bring up the browser driver *first*, then invoke
+the helper just before navigating — otherwise the token goes stale.
+
+### 2b. Navigate and wait
+
+1. Open the preview URL from Step 1 in the automation browser.
+2. Wait for the network to go idle and the initial render to complete.
+3. If the expected element isn't there, back off briefly and retry before
+   declaring failure — local dev pages sometimes hydrate in two phases.
+
+### 2c. Extract the subtree
+
+Two deterministic string operations — turning a component name into its
+`c-<kebab>` selector and wrapping the extracted HTML in the exact
+`DOM_OUTPUT_START` / `DOM_OUTPUT_END` markers — are handled by
+`<skill_dir>/scripts/extract-dom.sh`. Do NOT re-derive the selector or
+compose the markers in prose; call the script.
+
+Actual DOM traversal must be run by the browser-automation driver
+(Playwright / Puppeteer / CDP); the script does not drive the browser.
+
+#### If scope is `component`
+
+Compute the selector deterministically:
+
+```bash
+selector="$("<skill_dir>/scripts/extract-dom.sh" selector <componentName>)"
+```
+
+Then, using the driver, pierce the `lwr_dev-preview-container` shadow
+root, locate the first visible element matching `$selector`, and read its
+subtree HTML (via `element.shadowRoot.innerHTML`). Pipe that HTML into
+the wrap step:
+
+```bash
+printf '%s' "$html_subtree" \
+  | "<skill_dir>/scripts/extract-dom.sh" wrap component <componentName>
+```
+
+#### If scope is `app`
+
+Using the driver, identify the primary app root (prefer `document.body`
+or the main app container — not `document.documentElement`), exclude
+`<head>` and non-rendered nodes, and read the subtree HTML. Pipe it into
+the wrap step:
+
+```bash
+printf '%s' "$html_subtree" \
+  | "<skill_dir>/scripts/extract-dom.sh" wrap app
+```
+
+Emit the script's stdout unchanged as the DOM output.
+
+### 2d. About LWC Shadow DOM (the #1 gotcha)
+
+Lightning Web Components use Shadow DOM. The template content is **not**
+directly queryable on the host element:
+
+| Access pattern                | What you get                         |
+|-------------------------------|--------------------------------------|
+| `element.innerHTML`           | empty, or only slotted light-DOM content |
+| `element.outerHTML`           | just the host tag, no children       |
+| `element.shadowRoot.innerHTML`| the real rendered template content   |
+
+If the browser driver's DOM query doesn't pierce shadow roots by default,
+walk `shadowRoot` explicitly. Most modern automation drivers have a
+shadow-piercing query helper — use it.
+
+---
+
+## Examples
+
+For a worked end-to-end example (preview a component, capture the front-door
+URL safely, and extract its DOM), load
+[`examples/component-preview-and-dom.md`](examples/component-preview-and-dom.md).
+
+---
+
+## Verification Checklist
+
+- [ ] `<skill_dir>/scripts/verify-toolchain.sh <orgAlias>` exited zero for the target alias.
+- [ ] Preview command ran with `OPEN_BROWSER=false`.
+- [ ] Preview URL logged in the `Lightning Preview running at URL: <URL>` format.
+- [ ] Front-door URL fetched via `<skill_dir>/scripts/open-frontdoor.sh` (never `sf org open` directly).
+- [ ] DOM extraction used `shadowRoot` traversal (not `innerHTML` on the host).
+- [ ] DOM output was produced by `<skill_dir>/scripts/extract-dom.sh wrap …` (script owns the markers).
+
+---
+
+## Troubleshooting
+
+- **`verify-toolchain.sh` reports "Target org alias is not authenticated or not Connected"** —
+  run `sf org login web --alias <orgAlias>` (the alias must match the one
+  you passed to `verify-toolchain.sh` and the `-o` value the preview
+  command uses).
+- **`verify-toolchain.sh` reports the plugin is missing** — install it with
+  `sf plugins install @salesforce/plugin-lightning-dev`.
+- **Preview opens a browser window** — you forgot `OPEN_BROWSER=false`.
+- **Empty DOM on extraction** — you're looking at `innerHTML` on a host. Use
+  `element.shadowRoot.innerHTML` instead. Also verify you pierced the
+  `lwr_dev-preview-container` shadow root.
+- **Front-door token fails** — it's expired. Re-invoke
+  `<skill_dir>/scripts/open-frontdoor.sh` and navigate within ~60 seconds.

package/skills/experience-lwc-runtime-observe/examples/component-preview-and-dom.md

@@ -0,0 +1,41 @@
+# Example — preview a component and grab its DOM
+
+**User:** "Preview `accountTile` from my org `dev-sandbox` and give me the
+rendered HTML."
+
+**Agent:**
+1. `"<skill_dir>/scripts/verify-toolchain.sh" dev-sandbox` — passes.
+2. `OPEN_BROWSER=false sf lightning dev component -o dev-sandbox -n accountTile`
+3. Log: `Lightning Preview running at URL: http://localhost:3333/...`
+4. Capture the helper output first so a failure aborts the caller, then
+   eval the exports:
+   ```bash
+   frontdoor_env="$("<skill_dir>/scripts/open-frontdoor.sh" dev-sandbox http://localhost:3333/...)" || exit 1
+   eval "$frontdoor_env"
+   ```
+   `$FRONTDOOR_URL_FILE` and `$PREVIEW_URL` are now exported for the
+   browser process (do NOT read/print the tempfile's contents).
+5. Browser driver reads the URL from `$FRONTDOOR_URL_FILE`, navigates to
+   establish session, then deletes the file.
+6. Navigate to preview URL, wait for network idle.
+7. Compute the selector:
+   ```bash
+   selector="$("<skill_dir>/scripts/extract-dom.sh" selector accountTile)"
+   # → c-account-tile
+   ```
+8. Pierce `lwr_dev-preview-container` shadow root via the driver, find
+   the first `$selector` host, read `element.shadowRoot.innerHTML` into
+   `$html_subtree`, and wrap:
+   ```bash
+   printf '%s' "$html_subtree" \
+     | "<skill_dir>/scripts/extract-dom.sh" wrap component accountTile
+   ```
+   Emits:
+
+```text
+DOM_OUTPUT_START
+<c-account-tile>
+  <!-- rendered shadow DOM here -->
+</c-account-tile>
+DOM_OUTPUT_END
+```

package/skills/experience-lwc-runtime-observe/scripts/extract-dom.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Deterministic wrapper for runtime DOM extraction. Handles the two
+# operations that are pure string ops (and therefore should not be left to
+# an LLM):
+#   1. Convert a component name to its LWC selector (camelCase / PascalCase
+#      → kebab-case, prefixed with `c-`).
+#   2. Wrap an already-extracted DOM subtree in the exact
+#      DOM_OUTPUT_START / DOM_OUTPUT_END markers the harness expects.
+#
+# Actual DOM traversal must be done by the caller's browser-automation
+# driver (Playwright / Puppeteer / CDP) since the agent harness controls
+# the browser. Feed the extracted HTML into this script on stdin and its
+# marker-wrapped output goes to stdout.
+#
+# Usage:
+#   # 1. Compute the selector for a component
+#   <skill_dir>/scripts/extract-dom.sh selector accountTile
+#     → c-account-tile
+#
+#   # 2. Wrap an app-scope subtree captured by the browser driver
+#   printf '%s' "$html_subtree" | <skill_dir>/scripts/extract-dom.sh wrap app
+#
+#   # 3. Wrap a component-scope subtree (selector inferred from the name)
+#   printf '%s' "$html_subtree" | <skill_dir>/scripts/extract-dom.sh wrap component accountTile
+
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+usage:
+  extract-dom.sh selector <componentName>
+  extract-dom.sh wrap app
+  extract-dom.sh wrap component <componentName>
+EOF
+  exit 2
+}
+
+to_selector() {
+  local name="$1"
+  python3 - "$name" <<'PY'
+import re, sys
+name = sys.argv[1]
+kebab = re.sub(r'(?<!^)(?=[A-Z])', '-', name).lower()
+kebab = re.sub(r'[^a-z0-9]+', '-', kebab).strip('-')
+print(f"c-{kebab}")
+PY
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  selector)
+    [[ $# -eq 2 ]] || usage
+    to_selector "$2"
+    ;;
+  wrap)
+    scope="${2:-}"
+    case "$scope" in
+      app)
+        [[ $# -eq 2 ]] || usage
+        printf 'DOM_OUTPUT_START\n'
+        cat
+        printf '\nDOM_OUTPUT_END\n'
+        ;;
+      component)
+        [[ $# -eq 3 ]] || usage
+        selector="$(to_selector "$3")"
+        printf 'DOM_OUTPUT_START\n<%s>' "$selector"
+        cat
+        printf '</%s>\nDOM_OUTPUT_END\n' "$selector"
+        ;;
+      *)
+        usage
+        ;;
+    esac
+    ;;
+  *)
+    usage
+    ;;
+esac

package/skills/experience-lwc-runtime-observe/scripts/open-frontdoor.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Captures the Salesforce front-door URL into a mode-0600 tempfile without
+# printing it to stdout OR stderr, then hands the browser driver the path.
+# This keeps the OTP-bearing URL out of agent tool traces (S1: no auth
+# tokens in context).
+#
+# Usage (capture output first so a helper failure aborts the caller —
+# `eval "$(...)"` alone swallows the helper's nonzero exit status):
+#   frontdoor_env="$(scripts/open-frontdoor.sh <org-alias> <preview-url>)" || exit 1
+#   eval "$frontdoor_env"
+#   # now $FRONTDOOR_URL_FILE and $PREVIEW_URL are exported for children
+#
+# The browser automation driver must read the URL from the tempfile,
+# navigate to it, then delete the file. Do NOT `cat` this file into your
+# agent's stdout.
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "usage: $0 <org-alias> <preview-url>" >&2
+  exit 2
+fi
+
+ORG_ALIAS="$1"
+PREVIEW_URL="$2"
+
+TMP_URL_FILE="$(mktemp -t sf-frontdoor.XXXXXX)"
+chmod 600 "$TMP_URL_FILE"
+
+# Redirect BOTH stdout and stderr from sf and python3 so no URL fragment,
+# progress message, or JSON error trace can reach the agent's tool-output
+# stream. Only the extracted URL lands in $TMP_URL_FILE.
+if ! sf org open --url-only --json --target-org "$ORG_ALIAS" 2>/dev/null \
+     | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"]["url"])' 2>/dev/null \
+     > "$TMP_URL_FILE"
+then
+  rm -f "$TMP_URL_FILE"
+  echo "error: failed to capture front-door URL for org '$ORG_ALIAS'" >&2
+  exit 1
+fi
+
+# Emit `export` assignments so the caller must `eval` the output to make
+# the variables reach child processes (the browser driver). No token material
+# is printed — only the tempfile path and the preview URL.
+printf 'export FRONTDOOR_URL_FILE=%q\n' "$TMP_URL_FILE"
+printf 'export PREVIEW_URL=%q\n' "$PREVIEW_URL"

package/skills/experience-lwc-runtime-observe/scripts/verify-toolchain.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Verifies the toolchain required for Lightning Preview: `sf` CLI on PATH,
+# `@salesforce/plugin-lightning-dev` installed, and the specified target
+# org alias authenticated and Connected. Exits nonzero with an actionable
+# message on failure so the agent can surface a single, deterministic
+# error instead of parsing prose from three separate commands.
+#
+# Usage:
+#   <skill_dir>/scripts/verify-toolchain.sh <orgAlias>
+
+set -euo pipefail
+
+fail() {
+  echo "verify-toolchain: $*" >&2
+  exit 1
+}
+
+if [ "$#" -lt 1 ] || [ -z "${1:-}" ]; then
+  fail "usage: $0 <orgAlias>"
+fi
+alias="$1"
+
+command -v sf >/dev/null 2>&1 \
+  || fail "Salesforce CLI (\`sf\`) not found on PATH. Install via https://developer.salesforce.com/tools/salesforcecli then re-run."
+
+sf version >/dev/null 2>&1 \
+  || fail "\`sf version\` failed. Reinstall the Salesforce CLI."
+
+if ! sf plugins --core 2>/dev/null | grep -Eq '(^|[[:space:]])@salesforce/plugin-lightning-dev([[:space:]]|$)'; then
+  if ! sf plugins 2>/dev/null | grep -Eq '(^|[[:space:]])@salesforce/plugin-lightning-dev([[:space:]]|$)'; then
+    fail "Plugin \`@salesforce/plugin-lightning-dev\` is not installed. Install via: sf plugins install @salesforce/plugin-lightning-dev"
+  fi
+fi
+
+if ! sf org display --target-org "$alias" --json 2>/dev/null \
+     | python3 -c 'import json,sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+if d.get("status") != 0:
+    sys.exit(1)
+r = d.get("result", {}) or {}
+sys.exit(0 if r.get("connectedStatus") == "Connected" else 1)'; then
+  fail "Target org alias \`$alias\` is not authenticated or not Connected. Run \`sf org login web --alias $alias\` and re-run."
+fi
+
+echo "verify-toolchain: OK ($alias)"