@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/experience-ui-bundle-features-generate/scripts/detect-framework.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# detect-framework.sh — deterministic UI Bundle framework detector.
+#
+# Usage: bash detect-framework.sh [ROOT]
+#   ROOT  app or uiBundle root to inspect (default: current directory)
+#
+# Prints exactly one of the following tokens to stdout, nothing else, and sets
+# a matching exit code so callers can branch without parsing:
+#   react      (exit 0) — React signals only
+#   angular    (exit 0) — Angular signals only
+#   ambiguous  (exit 2) — both React and Angular signals present
+#   unknown    (exit 3) — neither framework detected
+#
+# Step 0 of the skill acts on the result: a single framework (exit 0) proceeds;
+# `ambiguous` asks the user to disambiguate; `unknown` TERMINATES the workflow
+# (no supported framework found — do not guess).
+
+set -u
+
+ROOT="${1:-.}"
+angular=0
+react=0
+
+# Resolve ROOT to an absolute path when possible (for the angular.json walk-up).
+abs_root="$(cd "$ROOT" 2>/dev/null && pwd || true)"
+
+# 1) angular.json at or above ROOT → Angular workspace.
+dir="$abs_root"
+while [ -n "$dir" ]; do
+  [ -f "$dir/angular.json" ] && angular=1
+  [ "$dir" = "/" ] && break
+  dir="$(dirname "$dir")"
+done
+
+# 2) package.json dependencies (excluding node_modules).
+while IFS= read -r pkg; do
+  [ -z "$pkg" ] && continue
+  grep -q '"@angular/core"' "$pkg" 2>/dev/null && angular=1
+  grep -Eq '"react"[[:space:]]*:' "$pkg" 2>/dev/null && react=1
+done <<EOF
+$(find "$ROOT" -type d -name node_modules -prune -o -type f -name package.json -print 2>/dev/null)
+EOF
+
+# 3) Source-file signatures (excluding node_modules).
+has_file() {
+  find "$ROOT" -type d -name node_modules -prune -o -type f -name "$1" -print 2>/dev/null | grep -q .
+}
+
+# Angular: component files, routing module, or @Component-decorated classes.
+has_file '*.component.ts' && angular=1
+has_file 'app.routes.ts' && angular=1
+if grep -rls --exclude-dir=node_modules --include='*.ts' '@Component' "$ROOT" 2>/dev/null | grep -q .; then
+  angular=1
+fi
+
+# React: JSX/TSX source files.
+has_file '*.tsx' && react=1
+has_file '*.jsx' && react=1
+
+if [ "$angular" -eq 1 ] && [ "$react" -eq 1 ]; then
+  echo ambiguous
+  exit 2
+elif [ "$angular" -eq 1 ]; then
+  echo angular
+  exit 0
+elif [ "$react" -eq 1 ]; then
+  echo react
+  exit 0
+else
+  echo unknown
+  exit 3
+fi

package/skills/experience-ui-bundle-frontend-generate/SKILL.md

@@ -60,11 +60,11 @@ A request to rename/rebrand the app (e.g. "call it X everywhere a user would see
 Some capabilities ship as pre-built, tested feature packages. The catalog **evolves and is not something you can know from memory** — never decide from the request wording alone whether a capability "is" or "isn't" a feature. Before hand-writing any non-trivial capability (anything beyond a plain page, component, or styling change) in this skill:
 
 1. **Consult the authoritative catalog.** Invoke `experience-ui-bundle-features-generate`, which runs `list` to show the *current* set of installable features. Do not rely on a hardcoded or remembered list — this skill deliberately names none, because any names it listed would go stale.
-2. **Detect whether a matching feature is already installed** in the bundle — inspect `package.json` dependencies and existing `src/` files. If present, use it as-is; do not reinstall or re-implement.
+2. **Detect whether a matching feature is already installed** in the bundle — inspect `package.json` dependencies and existing `src/` files. If present, do not reinstall or re-implement it — **but you must still adopt it**: invoke `experience-ui-bundle-features-generate` to `describe` it (which reads the feature's README — the adoption contract), wire it into the app, and, if the feature ships config (e.g. a `config.json`), set that for this app's data and use case. Installed-but-unconfigured is not done.
 3. **If a matching feature exists in the catalog but isn't installed**, let `experience-ui-bundle-features-generate` install the tested package. Do not build it from scratch here.
 4. **Only hand-build** a capability that has no matching catalog feature.
 
-This gate is **idempotent**: when this skill runs as a phase of `experience-ui-bundle-app-coordinate` (which installs features earlier in its sequence), step 2 finds the feature already present and this collapses to a no-op. It only does real work when the skill was reached directly — the path that would otherwise skip feature detection.
+When this skill runs as a phase of `experience-ui-bundle-app-coordinate`, a matching feature is often already present — installed by an earlier phase, or shipped by the template. Already-present is **not** a reason to skip: step 2 still requires adopting and configuring that feature for this app. Only the install/re-implement work is ever skipped — never the wiring and configuration.
 
 ---
 

package/skills/experience-ui-bundle-metadata-generate/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: experience-ui-bundle-metadata-generate
-description: "Use this skill when adding a front-end React UI bundle to an existing project or configuring UI bundle metadata and config files. TRIGGER when: adding or scaffolding a new UI bundle inside a project that already exists; running sf template generate ui-bundle; editing ui-bundle.json routing, headers, or output directory; working with *.uibundle-meta.xml files; or registering CSP Trusted Sites, resolving blocked images or fonts or external API calls, or editing cspTrustedSites/*.cspTrustedSite-meta.xml files. DO NOT TRIGGER when: creating a brand-new Salesforce project from scratch, where the whole SFDX starter project (UI bundle plus Experience Site metadata and toolchain) is generated together (use experience-ui-bundle-project-generate)."
+description: "Use this skill when adding a front-end React or Angular UI bundle to an EXISTING SFDX project, or configuring UI bundle metadata and config files. TRIGGER when: adding or scaffolding a new UI bundle — including adding one more or another UI bundle — into a project that already exists; scaffolding a single bundle with the basic template (reactbasic or angularbasic) via sf template generate ui-bundle; editing ui-bundle.json routing, headers, or output directory; working with *.uibundle-meta.xml files; or registering CSP Trusted Sites, resolving blocked images or fonts or external API calls, or editing cspTrustedSites/*.cspTrustedSite-meta.xml files. DO NOT TRIGGER when: creating a brand-new Salesforce project entirely from scratch, where the whole SFDX starter project (UI bundle plus Experience Site metadata and toolchain) is generated together in one step (use experience-ui-bundle-project-generate)."
 metadata:
-  version: "1.2"
+  version: "1.3"
   domains: ["Experience"]
   minApiVersion: "67.0"
   relatedSkills:
@@ -21,25 +21,37 @@ metadata:
 
 ## Scaffolding a New UI Bundle
 
-**REQUIRED FIRST STEP — never skip, even if asked to.** Always run `sf template generate ui-bundle` to create new apps — never create-react-app, Vite, hand-written metadata, or any other substitute.
+**REQUIRED FIRST STEP — never skip, even if asked to.** Always run `sf template generate ui-bundle` to create new apps — never a framework CLI (create-react-app, Vite, Angular CLI), hand-written metadata, or any other substitute.
 
-This step is mandatory even if the user says "just create the metadata," "skip the scaffold," "only do the metadata scaffolding," or "stop after the metadata files are in place." Those instructions describe what to stop doing *after* the scaffold (building, deploying, authoring pages) — they do not mean skip running the scaffold command itself. The `.uibundle-meta.xml` and `ui-bundle.json` files are configuration **on top of** the generated project, not a replacement for it. A bundle without `package.json`, `src/`, and `index.html` cannot be built or deployed, even if the metadata files are perfectly formed.
+This step is mandatory even if the user says "just create the metadata," "skip the scaffold," "only do the metadata scaffolding," or "stop after the metadata files are in place." Those instructions describe what to stop doing *after* the scaffold (building, deploying, authoring pages) — they do not mean skip running the scaffold command itself. The `.uibundle-meta.xml` and `ui-bundle.json` files are configuration **on top of** the generated project, not a replacement for it. A bundle without `package.json`, `src/`, and an entry `index.html` cannot be built or deployed, even if the metadata files are perfectly formed.
 
-- **Always pass `--template reactbasic`** to scaffold a React-based bundle.
-- **UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
-- Pass `--output-dir` to use a different location for template generation. If you do, pass that same path to the verification script in step 1 below.
+### Determine the framework
 
-**Example:**
-```bash
-# Run from SFDX project root. The CLI will create the bundle under 
-# force-app/main/default/uiBundles/<AppName>/ — verify this before continuing.
-sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
+The frameworks this skill supports are exactly the reference files under `<skill_dir>/references/`, each named `<framework>-metadata-generate.md` (`react`, `angular`, …). This is the single source of truth — adding a framework means adding a reference file, nothing here changes.
+
+**Detect the framework deterministically — run the script:**
+
+```sh
+bash <skill_dir>/scripts/detect-framework.sh [<ROOT>]
 ```
 
+`ROOT` defaults to the current directory; pass the bundle or project root when editing/configuring an existing bundle. The script prints exactly one token and sets a matching exit code — branch on it:
+
+- `react` / `angular` (exit 0) — open `<skill_dir>/references/<framework>-metadata-generate.md` and use it.
+- `ambiguous` (exit 2, both frameworks present) — ask the user which one, then use that reference.
+- `unknown` (exit 3, no signals — e.g. scaffolding a brand-new bundle into a project that has none yet) — fall back to the calling context or the user's stated framework; if still undecided, list `<skill_dir>/references/`, derive the supported set by stripping the `-metadata-generate.md` suffix from each filename, and ask the user to pick.
+
+If the calling context or the user already named the framework, that overrides detection — but still confirm a matching reference file exists. **Never guess.**
+
+The reference file gives you the exact `--template` flag, the entry-file layout, and the default boilerplate strings to replace for that framework.
+
+- **UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters.
+- Pass `--output-dir` to use a different location for template generation. If you do, pass that same path to the verification script in step 1 below.
+
 After generation:
-1. **Verify the scaffold is complete** — run `bash <skill_dir>/scripts/verify-bundle-location.sh <BundleName> [<CustomOutputDir>]` from the project root and follow any error output. This checks both the bundle's location AND that `package.json`, `src/`, and `index.html` exist — if any are missing, the scaffold step was skipped; go back and run `sf template generate ui-bundle` before continuing. Pass `<CustomOutputDir>` only if you used `--output-dir` during scaffolding; otherwise omit it.
+1. **Verify the scaffold is complete** — run `bash <skill_dir>/scripts/verify-bundle-location.sh <BundleName> [<CustomOutputDir>] [<framework>]` from the project root and follow any error output. This checks both the bundle's location AND that `package.json`, `src/`, and an entry `index.html` exist — if any are missing, the scaffold step was skipped; go back and run `sf template generate ui-bundle` before continuing. Pass `<CustomOutputDir>` only if you used `--output-dir` during scaffolding (pass `""` to skip it while still supplying a framework); pass `<framework>` (`react` or `angular`) so the remediation hint uses the right template.
 2. **Verify API version** — run `bash <skill_dir>/scripts/check-api-version.sh` from the project root to ensure `sourceApiVersion` in `sfdx-project.json` is 67.0 or higher. The script will automatically update it if needed.
-3. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
+3. Replace all default boilerplate — the framework reference file lists the exact stock `<title>` and placeholder strings to replace
 4. Populate the home page with real content (landing section, banners, hero, navigation)
 5. Update navigation and placeholders (see the `experience-ui-bundle-frontend-generate` skill)
 6. **Configure a hosting target** — a UI bundle without a `<target>` in its meta XML will not be visible in the org. Use `experience-ui-bundle-custom-app-generate` for internal (App Launcher) apps or `experience-ui-bundle-site-generate` for external (Experience Site) apps.

package/skills/experience-ui-bundle-metadata-generate/references/angular-metadata-generate.md

@@ -0,0 +1,37 @@
+# Angular UI Bundle Scaffold
+
+Reference for the **Angular** path of `experience-ui-bundle-metadata-generate`. Use this to scaffold the bundle, then return to the "After generation" steps in `SKILL.md`.
+
+## Scaffold command
+
+Always pass `--template angularbasic` to scaffold an Angular bundle:
+
+```bash
+# Run from SFDX project root. The CLI creates the bundle under
+# force-app/main/default/uiBundles/<AppName>/ — verify this before continuing.
+sf template generate ui-bundle -n CoffeeBoutique --template angularbasic
+```
+
+Pass `--output-dir` to generate at a different location. If you do, pass that same path to `verify-bundle-location.sh` in the verification step.
+
+## What the scaffold produces
+
+An Angular (TypeScript, standalone components) app under `force-app/main/default/uiBundles/<AppName>/`:
+
+- **Entry HTML:** `src/index.html` (NOT the bundle root), mounting `<app-root>` and carrying a `<base href="/">`.
+- **App entry:** `src/main.ts`; `src/app/app.ts` + `src/app/app.html`, `src/app/app.config.ts`, `src/app/app.routes.ts`; pages under `src/app/pages/`.
+- **Build:** Angular CLI driven by `angular.json` with the `@angular-builders/custom-esbuild:application` builder. Salesforce integration (API-version substitution, org proxy, Live Preview / `SFDC_ENV` / base-href injection) is wired via the esbuild plugin + `middleware/` — no `vite.config.ts`.
+- **Build output:** the builder's `outputPath.browser` is flattened to `dist/`, matching `ui-bundle.json` `outputDir: "dist"` — same as React.
+
+## Default boilerplate to replace
+
+Replace every stock string before shipping — searching for these is the fastest way to find them:
+
+- `<title>MyAngularApp</title>` in `src/index.html` → a real product title.
+- Default `<app-root>` welcome/landing markup in `src/app/app.html` and any placeholder page stubs under `src/app/pages/`.
+- Placeholder navigation and empty routes (see `experience-ui-bundle-frontend-generate`).
+
+## Notes
+
+- **Dev-server port / CSP:** the Angular bundle's dev server is `sf-angular-serve` (the `package.json` `dev` script, provided by `@salesforce/angular-plugin-ui-bundle`), whose default port is `5173` — the same as React's Vite default — overridable with `SF_UIBUNDLE_PORT`. No Angular-specific CSP Trusted Site change is needed for local dev vs React.
+- **Element/binding syntax:** Angular uses `<app-root>` and standalone components with native control flow (`@if` / `@for`) — not JSX. This only matters when authoring pages; the metadata and config files below are framework-neutral.

package/skills/experience-ui-bundle-metadata-generate/references/react-metadata-generate.md

@@ -0,0 +1,32 @@
+# React UI Bundle Scaffold
+
+Reference for the **React** path of `experience-ui-bundle-metadata-generate`. Use this to scaffold the bundle, then return to the "After generation" steps in `SKILL.md`.
+
+## Scaffold command
+
+Always pass `--template reactbasic` to scaffold a React/Vite bundle:
+
+```bash
+# Run from SFDX project root. The CLI creates the bundle under
+# force-app/main/default/uiBundles/<AppName>/ — verify this before continuing.
+sf template generate ui-bundle -n CoffeeBoutique --template reactbasic
+```
+
+Pass `--output-dir` to generate at a different location. If you do, pass that same path to `verify-bundle-location.sh` in the verification step.
+
+## What the scaffold produces
+
+A React + Vite (TypeScript) app under `force-app/main/default/uiBundles/<AppName>/`:
+
+- **Entry HTML:** `index.html` at the bundle root, mounting `<div id="root">` and loading `src/app.tsx`.
+- **App entry:** `src/app.tsx`; pages under `src/pages/`, components under `src/components/`.
+- **Toolchain:** `vite.config.ts`, `package.json`, shadcn/ui primitives, Tailwind, GraphQL client + `codegen.yml`.
+- **Build output:** `dist/` (matches `ui-bundle.json` `outputDir: "dist"`).
+
+## Default boilerplate to replace
+
+Replace every stock string before shipping — searching for these is the fastest way to find them:
+
+- `<title>Welcome to React App</title>` in `index.html` → a real product title.
+- Any "React App" / "Vite + React" placeholder copy and default hero/landing text.
+- Placeholder navigation and empty page stubs (see `experience-ui-bundle-frontend-generate`).

package/skills/experience-ui-bundle-metadata-generate/scripts/detect-framework.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+#
+# detect-framework.sh — deterministic UI Bundle framework detector.
+#
+# Usage: bash detect-framework.sh [ROOT]
+#   ROOT  app or uiBundle root to inspect (default: current directory)
+#
+# Prints exactly one of the following tokens to stdout, nothing else, and sets
+# a matching exit code so callers can branch without parsing:
+#   react      (exit 0) — React signals only
+#   angular    (exit 0) — Angular signals only
+#   ambiguous  (exit 2) — both React and Angular signals present
+#   unknown    (exit 3) — neither framework detected
+#
+# Step 0 of the skill acts on the result: a single framework (exit 0) proceeds;
+# `ambiguous` asks the user to disambiguate; `unknown` TERMINATES the workflow
+# (no supported framework found — do not guess).
+
+set -u
+
+ROOT="${1:-.}"
+angular=0
+react=0
+
+# Resolve ROOT to an absolute path when possible (for the angular.json walk-up).
+abs_root="$(cd "$ROOT" 2>/dev/null && pwd || true)"
+
+# 1) angular.json at or above ROOT → Angular workspace.
+dir="$abs_root"
+while [ -n "$dir" ]; do
+  [ -f "$dir/angular.json" ] && angular=1
+  [ "$dir" = "/" ] && break
+  dir="$(dirname "$dir")"
+done
+
+# 2) package.json dependencies (excluding node_modules).
+while IFS= read -r pkg; do
+  [ -z "$pkg" ] && continue
+  grep -q '"@angular/core"' "$pkg" 2>/dev/null && angular=1
+  grep -Eq '"react"[[:space:]]*:' "$pkg" 2>/dev/null && react=1
+done <<EOF
+$(find "$ROOT" -type d -name node_modules -prune -o -type f -name package.json -print 2>/dev/null)
+EOF
+
+# 3) Source-file signatures (excluding node_modules).
+has_file() {
+  find "$ROOT" -type d -name node_modules -prune -o -type f -name "$1" -print 2>/dev/null | grep -q .
+}
+
+# Angular: component files, routing module, or @Component-decorated classes.
+has_file '*.component.ts' && angular=1
+has_file 'app.routes.ts' && angular=1
+if grep -rls --exclude-dir=node_modules --include='*.ts' '@Component' "$ROOT" 2>/dev/null | grep -q .; then
+  angular=1
+fi
+
+# React: JSX/TSX source files.
+has_file '*.tsx' && react=1
+has_file '*.jsx' && react=1
+
+if [ "$angular" -eq 1 ] && [ "$react" -eq 1 ]; then
+  echo ambiguous
+  exit 2
+elif [ "$angular" -eq 1 ]; then
+  echo angular
+  exit 0
+elif [ "$react" -eq 1 ]; then
+  echo react
+  exit 0
+else
+  echo unknown
+  exit 3
+fi

package/skills/experience-ui-bundle-metadata-generate/scripts/verify-bundle-location.sh

@@ -1,25 +1,40 @@
 #!/bin/bash
 # Verifies that a UI bundle was created under force-app/main/default/uiBundles/
 # (and not at the repo root, which would be non-deployable), AND that the
-# scaffold itself is complete (package.json, src/, index.html present) — not
-# just a hand-authored metadata-only directory.
+# scaffold itself is complete (package.json, src/, entry index.html present) —
+# not just a hand-authored metadata-only directory.
+#
+# The entry index.html lives at the bundle root for React (reactbasic) and at
+# src/index.html for Angular (angularbasic), so both locations are accepted.
 #
 # If a custom output directory was used (--output-dir on the scaffold command),
 # pass it as the second argument. The script then verifies the bundle exists
-# there instead of assuming the default location.
+# there instead of assuming the default location. Pass the framework
+# (react|angular) as the third argument so the remediation hint uses the right
+# --template flag; pass "" for the second argument to supply only a framework.
 
 set -e
 
-if [[ $# -lt 1 || $# -gt 2 ]]; then
+if [[ $# -lt 1 || $# -gt 3 ]]; then
   echo "ERROR: Bundle name required"
-  echo "Usage: bash verify-bundle-location.sh <BundleName> [<CustomOutputDir>]"
+  echo "Usage: bash verify-bundle-location.sh <BundleName> [<CustomOutputDir>] [<framework>]"
   exit 1
 fi
 
 BUNDLE_NAME="$1"
 CUSTOM_OUTPUT_DIR="${2:-}"
+FRAMEWORK="${3:-}"
+
+# Pick the remediation template and the expected entry-HTML location from the
+# framework. When the framework is not supplied we stay lenient: default the
+# hint to reactbasic and accept the entry index.html at either location.
+case "$FRAMEWORK" in
+  angular) TEMPLATE="angularbasic"; ENTRY="src/index.html" ;;
+  react)   TEMPLATE="reactbasic";   ENTRY="index.html" ;;
+  *)       TEMPLATE="reactbasic";   ENTRY="" ;;
+esac
 
-# Checks that the scaffold actually produced a full React project, not just
+# Checks that the scaffold actually produced a full project, not just
 # hand-written metadata files. Returns 1 (and prints guidance) if incomplete.
 # Pass a second argument with the --output-dir value when checking a bundle
 # in a custom location, so the remediation command matches where the bundle
@@ -30,10 +45,17 @@ check_scaffold_complete() {
   local missing=()
   [[ -f "$bundle_path/package.json" ]] || missing+=("package.json")
   [[ -d "$bundle_path/src" ]] || missing+=("src/")
-  [[ -f "$bundle_path/index.html" ]] || missing+=("index.html")
+  # Entry HTML lives at the bundle root for React and at src/index.html for
+  # Angular. When the framework is known, require the correct location; when it
+  # is unknown, accept either.
+  if [[ -n "$ENTRY" ]]; then
+    [[ -f "$bundle_path/$ENTRY" ]] || missing+=("$ENTRY")
+  else
+    [[ -f "$bundle_path/index.html" || -f "$bundle_path/src/index.html" ]] || missing+=("index.html")
+  fi
 
   if [[ ${#missing[@]} -gt 0 ]]; then
-    local scaffold_cmd="sf template generate ui-bundle -n $BUNDLE_NAME --template reactbasic"
+    local scaffold_cmd="sf template generate ui-bundle -n $BUNDLE_NAME --template $TEMPLATE"
     if [[ -n "$output_dir" ]]; then
       scaffold_cmd="$scaffold_cmd --output-dir \"$output_dir\""
     fi

package/skills/experience-ui-bundle-project-generate/SKILL.md

@@ -113,4 +113,4 @@ From here, continue development with the other ui-bundle skills (`experience-ui-
 
 - The starters are **minimal** — no seeded sample data or custom objects. Build the rest with the other ui-bundle skills.
 - These templates use the `uiBundles` metadata convention. The UI bundle directory and meta XML are named after the project name you pass to `--name`.
-- `sf template generate project --help` lists all available templates if the flag names ever change.
+- `sf template generate project --help` lists all available templates if the flag names ever change.