@salesforce/afv-skills 1.33.0 → 1.35.0

package/skills/dx-apexguru-scan/scripts/run-scan.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Submit a zip to the ApexGuru SFAP Scan API and poll to completion.
+#
+# Usage:
+#   bash run-scan.sh <zip-path> <raw-result-out.json> [--org <alias>] [--fast]
+#                    [--max-polls N] [--interval SEC]
+#   The endpoint (prod/stage/dev host) is chosen by resolve-token.sh from the
+#   token's environment; customers on a prod org always hit api.salesforce.com.
+#
+# Steps:
+#   1. resolve-token.sh → baseUrl + JWT
+#   2. POST {baseUrl}/scan  (multipart file upload) → 202 {scanId, status}
+#   3. GET  {baseUrl}/scan/{scanId} every ~15s until SUCCEEDED/FAILED
+#   4. Write the final raw SUCCEEDED body verbatim to <raw-result-out.json>
+#      (report stays base64-encoded here; decode-report.js handles it).
+#
+# Progress lines go to STDERR so stdout stays a single clean JSON summary:
+#   {"scanId":"...","status":"SUCCEEDED","analysisMode":"static|full",
+#    "violationCount":N,"filesScanned":N,"rawResult":"<path>"}
+# On failure: {"error":"...","status":"...","httpStatus":NNN,"hint":"..."} exit 1.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+ZIP_PATH="${1:-}"
+RAW_OUT="${2:-}"
+shift 2 2>/dev/null || true
+
+FAST=""
+ORG_ALIAS=""
+MAX_POLLS=40          # 40 * 15s = 10 min ceiling
+INTERVAL=15
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --org) ORG_ALIAS="${2:-}"; shift 2 ;;
+    --fast) FAST="true"; shift ;;
+    --max-polls) MAX_POLLS="${2:-40}"; shift 2 ;;
+    --interval) INTERVAL="${2:-15}"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+
+err() { # msg httpStatus status hint
+  jq -cn --arg m "$1" --argjson h "${2:-0}" --arg s "${3:-}" --arg hint "${4:-}" \
+    '{error:$m, httpStatus:$h, status:$s, hint:$hint}'
+  exit 1
+}
+
+[ -n "$ZIP_PATH" ] && [ -f "$ZIP_PATH" ] || err "zip not found: $ZIP_PATH" 0 "" "run build-zip.sh first"
+[ -n "$RAW_OUT" ] || err "missing raw output path" 0 "" "usage: run-scan.sh <zip> <raw-out.json>"
+
+# --- 1. token ---
+RESOLVE_ARGS=()
+[ -n "$ORG_ALIAS" ] && RESOLVE_ARGS+=(--org "$ORG_ALIAS")
+CREDS="$(bash "$SCRIPT_DIR/resolve-token.sh" ${RESOLVE_ARGS[@]+"${RESOLVE_ARGS[@]}"})" || {
+  echo "$CREDS" >&2; exit 1;
+}
+BASE_URL="$(echo "$CREDS" | jq -r '.baseUrl')"
+# The JWT is a secret: resolve-token.sh returns a 0600 file PATH, never the token
+# itself. Read it into memory and delete the file right away so it never lingers.
+TOKEN_FILE="$(echo "$CREDS" | jq -r '.tokenFile')"
+TOKEN=""
+if [ -n "$TOKEN_FILE" ] && [ -f "$TOKEN_FILE" ]; then
+  TOKEN="$(cat "$TOKEN_FILE")"
+  rm -f "$TOKEN_FILE"
+fi
+[ -n "$TOKEN" ] || err "could not read resolved token" 0 "" "re-run; if it persists, resolve the token manually via APEXGURU_SFAP_TOKEN"
+
+hint_for_status() { # maps HTTP status → actionable hint (see references/error-handling.md)
+  case "$1" in
+    401) echo "Token bad or expired. Re-authenticate the Salesforce org (or supply a fresh sfap_api JWT) and retry." ;;
+    403) echo "Scan owned by a different org. The token's tnk-claim org must match the scan owner." ;;
+    404) echo "Unknown scanId, or the scan was archived (~30-day GC). Re-submit." ;;
+    400) echo "Malformed zip, no Apex inside, or over size limit (200MB compressed / 1GB decompressed)." ;;
+    *)   echo "See references/error-handling.md." ;;
+  esac
+}
+
+# Auto-enable fast mode if >10 Apex files (unless explicitly disabled)
+if [ -z "$FAST" ]; then
+  # grep -c exits non-zero when there are no matches; capture the count without
+  # letting that non-zero status trip `set -e`, and default an empty result to 0.
+  FILE_COUNT=$(unzip -l "$ZIP_PATH" 2>/dev/null | grep -c '\.cls$' || true)
+  FILE_COUNT=${FILE_COUNT:-0}
+  if [ "$FILE_COUNT" -gt 10 ]; then
+    FAST="true"
+    echo "Auto-enabling fast mode (detected $FILE_COUNT Apex files)" >&2
+  fi
+fi
+
+# --- 2. submit ---
+echo "Submitting scan to $BASE_URL/scan ..." >&2
+SUBMIT_BODY="$(mktemp)"
+FAST_ARG=()
+[ -n "$FAST" ] && FAST_ARG=(-F "fastMode=true")
+
+HTTP=$(curl -sS -o "$SUBMIT_BODY" -w '%{http_code}' -X POST "$BASE_URL/scan" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "x-apexguru-client: ApexGuru-Skill" \
+  -F "file=@${ZIP_PATH};type=application/zip" \
+  ${FAST_ARG[@]+"${FAST_ARG[@]}"}) || err "network error submitting scan" 0 "" "check connectivity to the API host"
+
+if [ "$HTTP" != "202" ] && [ "$HTTP" != "200" ]; then
+  MSG="$(jq -r '.message // .error // empty' "$SUBMIT_BODY" 2>/dev/null || true)"
+  rm -f "$SUBMIT_BODY"
+  err "submit failed: ${MSG:-HTTP $HTTP}" "$HTTP" "" "$(hint_for_status "$HTTP")"
+fi
+
+SCAN_ID="$(jq -r '.scanId // empty' "$SUBMIT_BODY")"
+rm -f "$SUBMIT_BODY"
+[ -n "$SCAN_ID" ] || err "no scanId in submit response" "$HTTP" "" "unexpected API response shape"
+echo "Accepted. scanId=$SCAN_ID (polling every ${INTERVAL}s, up to $MAX_POLLS times)..." >&2
+
+# --- 3. poll ---
+POLL_BODY="$(mktemp)"
+STATUS="QUEUED"
+i=0
+while [ "$i" -lt "$MAX_POLLS" ]; do
+  i=$((i + 1))
+  sleep "$INTERVAL"
+  HTTP=$(curl -sS -o "$POLL_BODY" -w '%{http_code}' -X GET "$BASE_URL/scan/$SCAN_ID" \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "x-apexguru-client: ApexGuru-Skill") || { echo "poll $i: network hiccup, retrying" >&2; continue; }
+
+  if [ "$HTTP" != "200" ]; then
+    MSG="$(jq -r '.message // .error // empty' "$POLL_BODY" 2>/dev/null || true)"
+    rm -f "$POLL_BODY"
+    err "poll failed: ${MSG:-HTTP $HTTP}" "$HTTP" "$STATUS" "$(hint_for_status "$HTTP")"
+  fi
+
+  STATUS="$(jq -r '.status // "UNKNOWN"' "$POLL_BODY")"
+  echo "poll $i/$MAX_POLLS: $STATUS" >&2
+
+  case "$STATUS" in
+    SUCCEEDED)
+      cp "$POLL_BODY" "$RAW_OUT"
+      rm -f "$POLL_BODY"
+      jq -c '{status, violationCount, filesScanned, rawResult: "'"$RAW_OUT"'"}' "$RAW_OUT"
+      exit 0
+      ;;
+    FAILED)
+      MSG="$(jq -r '.message // "scan reported FAILED"' "$POLL_BODY")"
+      rm -f "$POLL_BODY"
+      err "$MSG" "$HTTP" "FAILED" "Inspect the message; re-submit after addressing it."
+      ;;
+    QUEUED|RUNNING) : ;; # keep polling
+    *) echo "poll $i: unexpected status '$STATUS', continuing" >&2 ;;
+  esac
+done
+
+rm -f "$POLL_BODY"
+err "scan did not finish within $((MAX_POLLS * INTERVAL))s (last status: $STATUS)" 0 "$STATUS" \
+  "Large projects can take longer — re-run with --max-polls higher, or use --fast."

package/skills/dx-apexguru-scan/scripts/scan.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# One-shot ApexGuru performance scan: package → submit+poll → decode+present.
+#
+# This wrapper runs all three steps of the workflow in a single command so the
+# scan cannot be left half-finished (a bare run-scan.sh already prints a
+# violation count, which can read as "done" and tempt an early stop before the
+# report is decoded). The FINAL stdout of this script is the ready-to-present
+# markdown report from decode-report.js --present — print that to the user
+# verbatim.
+#
+# Usage:
+#   bash scan.sh <project-root> [--out <report.md>]
+#                [--org <alias>] [--fast] [--raw <raw-out.json>]
+#
+#   <project-root>  folder that contains Apex somewhere beneath it (defaults to
+#                   CWD if omitted or given as "."). build-zip.sh collects every
+#                   .cls/.trigger under it, any layout.
+#   --out FILE      also write the presented markdown to FILE (e.g. report.md).
+#   --org ALIAS     forwarded to run-scan.sh (which sf org to derive the JWT from).
+#   --fast          forwarded to run-scan.sh (skip LLM-heavy fix generation).
+#   --raw FILE      keep the raw SUCCEEDED JSON at FILE (default: a temp file).
+#
+# The endpoint (prod/stage/dev) is chosen from the token's env by resolve-token.sh;
+# customers on a prod org always hit api.salesforce.com.
+#
+# Progress for each step streams to STDERR; only the final presented markdown
+# goes to STDOUT. On any step failure, the failing step's JSON error/hint is
+# surfaced to stderr and the script exits non-zero.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+PROJECT_ROOT=""
+OUT_FILE=""
+RAW_OUT=""
+ORG_ALIAS=""
+FAST=""
+
+# First non-flag arg is the project root.
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --out) OUT_FILE="${2:-}"; shift 2 ;;
+    --raw) RAW_OUT="${2:-}"; shift 2 ;;
+    --org) ORG_ALIAS="${2:-}"; shift 2 ;;
+    --fast) FAST="--fast"; shift ;;
+    *) [ -z "$PROJECT_ROOT" ] && PROJECT_ROOT="$1"; shift ;;
+  esac
+done
+
+[ -n "$PROJECT_ROOT" ] || PROJECT_ROOT="$(pwd)"
+[ "$PROJECT_ROOT" = "." ] && PROJECT_ROOT="$(pwd)"
+
+TS="$(date +%Y%m%d-%H%M%S)"
+WORK_DIR="$(mktemp -d)"
+ZIP_PATH="$WORK_DIR/apexguru-${TS}.zip"
+[ -n "$RAW_OUT" ] || RAW_OUT="$WORK_DIR/apexguru-raw-${TS}.json"
+
+cleanup() { [ -n "${WORK_DIR:-}" ] && rm -rf "$WORK_DIR" 2>/dev/null || true; }
+trap cleanup EXIT
+
+# --- Step 1: package the project's Apex into a zip ---
+echo "[scan] Step 1/3: packaging $PROJECT_ROOT ..." >&2
+ZIP_JSON="$(bash "$SCRIPT_DIR/build-zip.sh" "$PROJECT_ROOT" "$ZIP_PATH")" || {
+  echo "$ZIP_JSON" >&2
+  echo "[scan] packaging failed — see the error/hint above." >&2
+  exit 1
+}
+echo "[scan] packaged: $(echo "$ZIP_JSON" | jq -r '.humanSize // "?"') → $(echo "$ZIP_JSON" | jq -r '.zip')" >&2
+
+# --- Step 2: submit + poll to completion ---
+echo "[scan] Step 2/3: submitting and polling the scan ..." >&2
+RUN_ARGS=("$ZIP_PATH" "$RAW_OUT")
+[ -n "$ORG_ALIAS" ] && RUN_ARGS+=(--org "$ORG_ALIAS")
+[ -n "$FAST" ] && RUN_ARGS+=("$FAST")
+RUN_JSON="$(bash "$SCRIPT_DIR/run-scan.sh" "${RUN_ARGS[@]}")" || {
+  echo "$RUN_JSON" >&2
+  echo "[scan] scan failed — see the error/hint above." >&2
+  exit 1
+}
+echo "[scan] scan complete: $(echo "$RUN_JSON" | jq -r '.violationCount // "?"') violations" >&2
+
+# --- Step 3: decode + present (this is the deliverable) ---
+echo "[scan] Step 3/3: decoding and presenting the report ..." >&2
+PRESENTED="$(node "$SCRIPT_DIR/decode-report.js" "$RAW_OUT" --present)" || {
+  echo "[scan] decoding failed against $RAW_OUT" >&2
+  exit 1
+}
+
+# Optionally persist the presented markdown (e.g. so it survives temp cleanup).
+if [ -n "$OUT_FILE" ]; then
+  printf '%s\n' "$PRESENTED" > "$OUT_FILE"
+  echo "[scan] report also written to $OUT_FILE" >&2
+fi
+
+# FINAL stdout: the ready-to-present markdown. Print this to the user verbatim.
+printf '%s\n' "$PRESENTED"

package/skills/dx-apexguru-scan/scripts/validate-token.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// Locally sanity-check an SFAP JWT *before* any network call, so a bad token
+// fails fast with a clear reason instead of a bare HTTP 401 deep in the poll
+// loop. This does NOT verify the signature (only the server can) — it decodes
+// the freely-readable header/body claims to catch the two things that cause
+// almost every 401: missing sfap_api scope, or expired.
+//
+// The token's environment (prod/stage/dev) is detected from its tnk claim and
+// reported as detectedEnv so the caller can route to the matching endpoint.
+//
+// The token is read from STDIN (never argv) so it does not leak into the
+// process list. Usage:
+//   printf '%s' "$JWT" | node validate-token.js [--now <epoch>]
+//
+// Output (stdout, single-line JSON):
+//   pass:  {"ok":true,"tnk":"...","detectedEnv":"prod|stage|dev|null","expiresInSeconds":N,"warnings":[...]}
+//   fail:  {"ok":false,"error":"...","hint":"..."}  (exit 1)
+// A "fail" only happens for things we can PROVE wrong (expired / missing scope).
+// Anything we cannot read is a warning, not a block.
+
+function out(obj, code) {
+  console.log(JSON.stringify(obj));
+  process.exit(code);
+}
+
+const args = process.argv.slice(2);
+let now = Math.floor(Date.now() / 1000);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--now") now = parseInt(args[++i], 10) || now;
+}
+
+// Read the token from stdin (keeps it out of argv / process list).
+let token = "";
+try {
+  token = require("fs").readFileSync(0, "utf8").trim();
+} catch {
+  token = "";
+}
+if (!token) out({ ok: false, error: "no token on stdin", hint: "resolve the token before validating" }, 1);
+
+// A JWT is header.body.signature, each a base64url-encoded chunk.
+function decodeSegment(seg) {
+  const b64 = seg.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+  return JSON.parse(Buffer.from(pad, "base64").toString("utf8"));
+}
+
+const parts = token.split(".");
+if (parts.length < 2) {
+  // Not a JWT we can read — don't block (token may be an opaque format).
+  out({ ok: true, tnk: null, detectedEnv: null, expiresInSeconds: null, warnings: ["token is not a readable JWT — skipping local checks"] }, 0);
+}
+
+let header, body;
+try {
+  header = decodeSegment(parts[0]);
+  body = decodeSegment(parts[1]);
+} catch {
+  out({ ok: true, tnk: null, detectedEnv: null, expiresInSeconds: null, warnings: ["could not decode JWT claims — skipping local checks"] }, 0);
+}
+
+const warnings = [];
+
+// --- 1. tnk / environment. Per the SFAP contract, tnk lives on the HEADER and
+// looks like core/<instance>/<orgId> (e.g. core/prod/00D..., core/stagecomstg2/...,
+// core/falcondeva/...). The environment marker lives ONLY in the <instance>
+// segment — the trailing <orgId> (00D...) is an opaque id that must NOT be
+// scanned for substrings, or a prod org whose id happens to contain "dev"/"stg"
+// would be wrongly rejected. So we match markers against the instance segment
+// and the iss host only, never the whole claim string. The detected env is
+// reported (not rejected) so the caller can route to the matching endpoint. ---
+const tnk = header.tnk || body.tnk || null;
+const iss = body.iss || "";
+// tnk instance segment = the middle of core/<instance>/<orgId>; fall back to the
+// whole tnk only if it isn't in that 3-part shape.
+const tnkParts = tnk ? String(tnk).split("/") : [];
+const tnkInstance = tnkParts.length >= 3 ? tnkParts[1] : tnk || "";
+// iss host (strip scheme/path) so we match the host label, not a full URL.
+const issHost = String(iss).replace(/^https?:\/\//, "").split(/[/?#]/)[0];
+const envHay = `${tnkInstance} ${issHost}`.toLowerCase();
+const looksDev = /falcondeva|falcondev|falcontest|deva|(^|[^a-z])dev([^a-z]|$)/.test(envHay);
+const looksStage = /stg|stage/.test(envHay);
+// Env inferred from the token's own claims (null when we can't tell). Production
+// instances carry no stg/dev marker, so a readable tnk with neither signal is prod.
+const detectedEnv = looksStage && !looksDev
+  ? "stage"
+  : looksDev && !looksStage
+  ? "dev"
+  : tnk && !looksStage && !looksDev
+  ? "prod"
+  : null;
+
+if (!tnk) warnings.push("no tnk claim found — could not detect the token's environment; defaulting to prod endpoint");
+
+// --- 2. scope must include sfap_api. Scope may be a space-delimited string
+// (scp/scope) or an array. Only fail if we can read it AND sfap_api is absent. ---
+const scopeRaw = body.scp ?? body.scope ?? null;
+if (scopeRaw != null) {
+  const scopes = Array.isArray(scopeRaw) ? scopeRaw : String(scopeRaw).split(/\s+/);
+  if (!scopes.includes("sfap_api")) {
+    out({ ok: false, error: "token scope does not include sfap_api",
+          hint: "Re-mint the token with the sfap_api scope. See references/authentication.md." }, 1);
+  }
+} else {
+  warnings.push("no scope claim found — could not confirm sfap_api scope");
+}
+
+// --- 3. expiry. exp is epoch seconds. Fail if already past. ---
+let expiresInSeconds = null;
+if (typeof body.exp === "number") {
+  expiresInSeconds = body.exp - now;
+  if (expiresInSeconds <= 0) {
+    out({ ok: false, error: `token expired ${Math.abs(expiresInSeconds)}s ago`,
+          hint: "Re-mint a fresh SFAP token and retry." }, 1);
+  }
+  if (expiresInSeconds < 60) warnings.push(`token expires in ${expiresInSeconds}s — it may lapse mid-scan`);
+} else {
+  warnings.push("no exp claim found — could not confirm the token is unexpired");
+}
+
+out({ ok: true, tnk, detectedEnv, expiresInSeconds, warnings }, 0);

package/skills/dx-app-analytics-query/SKILL.md

@@ -2,6 +2,11 @@
 name: dx-app-analytics-query
 description: "ISV App Analytics metadata types — AppAnalyticsQueryRequest and AppAnalyticsSettings. Use this skill when the user asks about retrieving managed package usage data, configuring App Analytics simulation mode, querying subscriber snapshots, or understanding the AppAnalyticsQueryRequest lifecycle (New → Pending → Complete → Expired). TRIGGER when: user mentions App Analytics, AppAnalyticsQueryRequest, AppAnalyticsSettings, package usage data, subscriber analytics, ISV analytics, or simulation mode for app analytics. DO NOT TRIGGER when: the task is about standard Salesforce reports/dashboards (use reporting skills), custom SOQL on Account/Contact (use platform-soql-query), or Data Cloud query/search (use data360-query)."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "platform-soql-query"
   version: "1.0"
   minApiVersion: "56.0"
 ---

package/skills/dx-code-analyzer-configure/SKILL.md

@@ -7,18 +7,18 @@ metadata:
     - "dx-code-analyzer-run"
     - "dx-code-analyzer-custom-rule-create"
   cliTools:
-    - tool: ["sf"]
-      semver: ">=2.0.0"
+    - tool: ["curl"]
+      semver: ">=7.0.0"
     - tool: ["java"]
       semver: ">=11.0.0"
     - tool: ["node"]
       semver: ">=18.0.0"
+    - tool: ["npm"]
+      semver: ">=9.0.0"
     - tool: ["python3"]
       semver: ">=3.10.0"
-    - tool: ["git"]
+    - tool: ["sf"]
       semver: ">=2.0.0"
-    - tool: ["npm"]
-      semver: ">=9.0.0"
 ---
 
 # Configuring Code Analyzer Skill

package/skills/dx-code-analyzer-custom-rule-create/SKILL.md

@@ -7,12 +7,14 @@ metadata:
     - "dx-code-analyzer-run"
     - "dx-code-analyzer-configure"
   cliTools:
-    - tool: ["sf"]
+    - tool: ["git"]
       semver: ">=2.0.0"
     - tool: ["node"]
       semver: ">=18.0.0"
     - tool: ["npm"]
       semver: ">=9.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # dx-code-analyzer-custom-rule-create: Custom Code Analyzer Rule Authoring

package/skills/dx-code-analyzer-run/SKILL.md

@@ -7,11 +7,19 @@ metadata:
     - "dx-code-analyzer-configure"
     - "dx-code-analyzer-custom-rule-create"
   cliTools:
-    - tool: ["sf"]
+    - tool: ["git"]
       semver: ">=2.0.0"
+    - tool: ["java"]
+      semver: ">=11.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
     - tool: ["node"]
       semver: ">=18.0.0"
-    - tool: ["git"]
+    - tool: ["npm"]
+      semver: ">=9.0.0"
+    - tool: ["python3"]
+      semver: ">=3.9.0"
+    - tool: ["sf"]
       semver: ">=2.0.0"
 ---