@salesforce/afv-skills 1.56.0 → 1.58.0

package/skills/experience-lwc-legacy-migrate/scripts/convert-lo-names.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Deterministic Lightning Out Beta -> LO 2.0 name/URL transforms.
+
+The Beta -> LO 2.0 migration includes a few *purely mechanical* string
+conversions that must be applied identically every time (Workflow B, Step B3):
+
+  * Aura component id ``c:myComponent`` -> LWC custom-element tag ``c-my-component``
+  * camelCase attribute names -> kebab-case HTML attribute names
+  * the org My Domain -> the versioned LO 2.0 library ``<script>`` URL
+
+This script performs those conversions so the workflow never has to hand-derive
+them. It does NOT make any judgement calls (target DOM location, whether an LO
+2.0 App id is needed, placeholder values) -- those stay in the skill body.
+
+Usage:
+  python3 scripts/convert-lo-names.py \
+      --component c:myComponent \
+      --attributes recordId,ownerId,showRevenue \
+      --my-domain https://acme.my.salesforce.com
+
+Any of the flags may be omitted; only the requested conversions are printed.
+Exit code is 0 on success, 2 on a malformed argument.
+"""
+import argparse
+import re
+import sys
+
+LO2_LIBRARY_PATH = "/lightning/lightning.out.latest/index.iife.prod.js"
+
+
+def camel_to_kebab(name: str) -> str:
+    """myComponent / MyComponent / my_component -> my-component."""
+    name = name.strip().replace("_", "-")
+    # split camelCase / PascalCase boundaries
+    name = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", name)
+    name = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1-\2", name)
+    return name.lower()
+
+
+def component_tag(aura_id: str) -> str:
+    """c:myComponent -> c-my-component (namespace preserved)."""
+    aura_id = aura_id.strip()
+    if ":" in aura_id:
+        ns, name = aura_id.split(":", 1)
+    else:
+        ns, name = "c", aura_id
+    return f"{ns.strip().lower()}-{camel_to_kebab(name)}"
+
+
+def library_url(my_domain: str) -> str:
+    """Normalize a My Domain to the versioned LO 2.0 library URL."""
+    d = my_domain.strip().rstrip("/")
+    if not d.startswith("http"):
+        d = "https://" + d
+    # Beta hosts on *.lightning.force.com; LO 2.0 must load from *.my.salesforce.com
+    d = d.replace(".lightning.force.com", ".my.salesforce.com")
+    # strip any path the caller pasted, keep scheme://host
+    m = re.match(r"(https?://[^/]+)", d)
+    host = m.group(1) if m else d
+    return f"{host}{LO2_LIBRARY_PATH}"
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--component", help="Beta component id, e.g. c:myComponent")
+    p.add_argument("--attributes",
+                   help="comma/space separated camelCase attribute names")
+    p.add_argument("--my-domain",
+                   help="org My Domain or Beta host URL")
+    args = p.parse_args(argv)
+
+    if not (args.component or args.attributes or args.my_domain):
+        p.print_help()
+        return 2
+
+    if args.component:
+        print(f"component-tag: <{component_tag(args.component)}>")
+
+    if args.attributes:
+        raw = [a for a in re.split(r"[,\s]+", args.attributes) if a]
+        pairs = [(a, camel_to_kebab(a)) for a in raw]
+        print("attributes:")
+        for src, dst in pairs:
+            print(f"  {src} -> {dst}")
+
+    if args.my_domain:
+        print(f"library-url: {library_url(args.my_domain)}  (add the `async` attribute)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/experience-lwc-legacy-migrate/scripts/validate-lo20-page.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Mechanically validate a migrated Lightning Out 2.0 host page.
+
+The six non-negotiable LO 2.0 rules (Workflow B, Step B4) plus the core
+library/component checklist items are all *deterministic code-structure*
+checks. This script runs them against a migrated HTML host page so the
+workflow gates on a repeatable pass/fail instead of prose interpretation.
+
+Usage:
+  python3 scripts/validate-lo20-page.py <path-to-migrated.html>
+
+Prints one PASS/FAIL line per rule. Exits 0 only when every rule passes;
+exits 1 if any rule fails, 2 on a usage/IO error.
+"""
+import re
+import sys
+
+
+def check(src: str):
+    """Return a list of (ok: bool, label: str, detail: str)."""
+    results = []
+
+    def add(ok, label, detail=""):
+        results.append((ok, label, detail))
+
+    # --- Library / Beta removal -------------------------------------------
+    # Locate the versioned library path, then scan back to the opening
+    # <script to check for `async`. We do NOT isolate the tag with [^>]*
+    # because placeholder URLs like https://<DOMAIN>.my.salesforce.com
+    # legitimately contain a '>' inside the attribute value.
+    lib_path = "lightning.out.latest/index.iife.prod.js"
+    idx = src.find(lib_path)
+    has_lo2_lib = idx != -1
+    lib_async = False
+    if has_lo2_lib:
+        start = src.rfind("<script", 0, idx)
+        if start != -1:
+            lib_async = bool(re.search(r"\basync\b", src[start:idx]))
+    add(has_lo2_lib and lib_async, "LO 2.0 library script tag",
+        "must load .../lightning.out.latest/index.iife.prod.js with `async`")
+
+    beta_lib = bool(re.search(r"lightning\.force\.com/[^\"']*lightning\.out\.js", src))
+    beta_calls = bool(re.search(r"\$Lightning\.(use|createComponent)", src))
+    add(not beta_lib and not beta_calls, "No Lightning Out Beta remnants",
+        "no lightning.out.js / $Lightning.use / $Lightning.createComponent")
+
+    # --- Rule 1: customElements.whenDefined must use a literal string ------
+    wd = re.findall(r"customElements\.whenDefined\(\s*([^)]*?)\s*\)", src)
+    if not wd:
+        add(False, "Rule 1: whenDefined literal string",
+            "no customElements.whenDefined(...) call found")
+    else:
+        # Require the ENTIRE trimmed argument to be a single quoted string
+        # literal. A prefix-only check (starts with a quote) would let
+        # expressions like `'c-' + componentTag` slip through.
+        all_literal = all(
+            re.fullmatch(r"""(['"]).*?\1""", arg.strip()) for arg in wd)
+        add(all_literal, "Rule 1: whenDefined literal string",
+            "argument must be a quoted string, not the `components` variable")
+
+    # --- Rule 2: mountLo20 declared with two parameters -------------------
+    decl = re.search(r"function\s+mountLo20\s*\(([^)]*)\)", src)
+    if not decl:
+        add(False, "Rule 2: mountLo20(frontdoorUrl, orgUrl)",
+            "no `function mountLo20(...)` declaration found")
+    else:
+        params = [p for p in decl.group(1).split(",") if p.strip()]
+        add(len(params) == 2, "Rule 2: mountLo20(frontdoorUrl, orgUrl)",
+            f"declaration has {len(params)} parameter(s), expected 2")
+
+    # --- Rule 3: clearCachedResult present (called before mounting) -------
+    add(bool(re.search(r"clearCachedResult\s*\(", src)),
+        "Rule 3: clearCachedResult() before mount",
+        "clearCachedResult() must run before every mountLo20() call")
+
+    # --- Rule 4: every mountLo20 call passes two arguments ----------------
+    calls = re.findall(r"(?<!function\s)\bmountLo20\s*\(([^)]*)\)", src)
+    # Count args for EVERY call site (the declaration is excluded by the
+    # lookbehind). Do NOT skip empty argument lists: a zero-arg
+    # `mountLo20()` has an arg count of 0, which is != 2 and must fail.
+    bad_calls = [c for c in calls
+                 if len([a for a in c.split(",") if a.strip()]) != 2]
+    add(len(bad_calls) == 0, "Rule 4: mountLo20 calls pass two args",
+        f"{len(bad_calls)} call(s) do not pass exactly two arguments")
+
+    # --- Rule 5: boot() wrapper defined and invoked -----------------------
+    boot_def = bool(re.search(r"function\s+boot\s*\(", src))
+    boot_call = bool(re.search(r"(?<!function\s)\bboot\s*\(\s*\)", src))
+    add(boot_def and boot_call, "Rule 5: boot() wrapper",
+        "define function boot() and call boot() once at the end")
+
+    # --- Rule 6: component tag has no inline display style ----------------
+    comp_tags = re.findall(r"<c-[a-z0-9-]+[^>]*>", src)
+    add(len(comp_tags) > 0, "Component tag present",
+        "expected a <c-...> custom element in the HTML")
+    inline_hidden = any(re.search(r"style\s*=\s*['\"][^'\"]*display\s*:\s*none",
+                                  t) for t in comp_tags)
+    add(not inline_hidden, "Rule 6: no inline display:none on component tag",
+        "control visibility via the loading indicator, not the component tag")
+
+    return results
+
+
+def main(argv=None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+    if len(argv) != 1:
+        print("usage: validate-lo20-page.py <path-to-migrated.html>",
+              file=sys.stderr)
+        return 2
+    try:
+        with open(argv[0], "r", encoding="utf-8") as fh:
+            src = fh.read()
+    except OSError as e:
+        print(f"error: cannot read {argv[0]}: {e}", file=sys.stderr)
+        return 2
+
+    results = check(src)
+    failed = 0
+    for ok, label, detail in results:
+        mark = "PASS" if ok else "FAIL"
+        line = f"[{mark}] {label}"
+        if not ok and detail:
+            line += f" -- {detail}"
+        print(line)
+        if not ok:
+            failed += 1
+
+    print(f"\n{len(results) - failed}/{len(results)} checks passed")
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -1,6 +1,6 @@
 ---
 name: experience-ui-bundle-project-generate
-description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce UI bundle app (React or Angular) and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); or when the user explicitly says they want to hand-scaffold from scratch."
+description: "Generates a minimal, ready-to-develop SFDX starter project from template instead of hand-scaffolding files. Use this skill when starting a brand-new Salesforce UI bundle app (React or Angular) and the initial project must be scaffolded — trigger phrases include create, start, or scaffold a new UI bundle app, generate a starter project, or use a prebuilt/starter template. DO NOT TRIGGER when: editing, styling, or adding pages or components to an EXISTING app (use experience-ui-bundle-frontend-generate); configuring ui-bundle.json or metadata files (use experience-ui-bundle-metadata-generate); deploying to an org (use experience-ui-bundle-deploy); when the user explicitly says they want to hand-scaffold from scratch; or when creating a brand-new standalone Salesforce project that also needs full setup — relocating the session, connecting an org, setting the default, and enabling source tracking (use dx-project-create in the salesforce-development plugin)."
 metadata:
   version: "1.2"
   domains: ["Experience"]
@@ -42,39 +42,22 @@ Once the user picks, carry the chosen `--template` flag into Step 2.
 
 ## Step 2: Generate the project into the target root
 
-The project contents must land **directly at the target root `$DEST`** — so `sfdx-project.json` sits at `$DEST/sfdx-project.json`, with no extra wrapper subfolder. `sf template generate project` always nests its output under a `--name` subfolder, so generate into the `$DEST` dir, then move the contents from the subfolder up into `$DEST`, overwriting anything already there on conflict. Remove the empty subfolder at the end.
+The project contents must land **directly at the target root `$DEST`** — so `sfdx-project.json` sits at `$DEST/sfdx-project.json`, with no extra wrapper subfolder. `sf template generate project` always nests its output under a `--name` subfolder, so `<SKILL_DIR>/scripts/generate-project.mjs` generates into `$DEST`, flattens the subfolder's contents up into `$DEST` (overwriting anything already there on conflict), and removes the now-empty subfolder — all through Node's `fs`/`child_process` APIs, so it runs the same way on Windows cmd/PowerShell as it does on macOS/Linux/Git Bash.
 
 - `<SKILL_DIR>` = the absolute path to **this skill's own directory** — the folder containing this `SKILL.md`; resolve it from the skill path in context
 - **`$NAME`** — the project name (alphanumerical only — no spaces, hyphens, underscores, or special characters). Ask the user for it. It also names the UI bundle, so it shows up inside the project.
 - **`$DEST`** — the target root directory the contents land in (use `.` for the current directory).
+- **`$TEMPLATE`** — the `--template` flag value from the framework reference chosen in Step 1 (e.g. `reactinternalapp`).
 
-```sh
-NAME=MyApp   # project name the user chose; also names the UI bundle
-DEST=.       # target root directory (the contents land directly here, no NAME/ wrapper)
-
-# the --template flag from the framework reference chosen in Step 1
-TEMPLATE=reactinternalapp   # example placeholder — replace with the flag from your Step-1 reference
-
-mkdir -p "$DEST"
-sf template generate project --name "$NAME" --template "$TEMPLATE" --output-dir "$DEST"
-
-# Flatten the generated $DEST/$NAME contents up into $DEST (see <SKILL_DIR>/scripts/flatten-project.mjs).
-# Use the absolute skill-dir path — a relative ./scripts/ would resolve against $DEST, not the skill.
-node "<SKILL_DIR>/scripts/flatten-project.mjs" "$DEST/$NAME" "$DEST"
-rm -rf "$DEST/$NAME"
-```
-
-> `<SKILL_DIR>/scripts/flatten-project.mjs` moves every generated entry (incl. dotfiles) into `$DEST`, overwriting any existing file/dir of any type on conflict while preserving unrelated files the user already had in `$DEST`. The per-entry `rmSync` + `renameSync` is what guarantees the template's files win on conflict (including a file-vs-directory type mismatch).
-
-### Verify
-
-After generation, confirm the contents landed at the root (not in a `$NAME/` subfolder):
+Run the script with the actual, literal values substituted for `$NAME`, `$DEST`, and `$TEMPLATE` — do not use shell variable assignment/interpolation (`NAME=...` / `$NAME` / `%NAME%` / `$env:NAME`) since that syntax differs across bash, cmd, and PowerShell and this command must work in all three:
 
 ```sh
-test -f "$DEST/sfdx-project.json" && echo "OK: project root landed" || echo "FAILED"
+node "<SKILL_DIR>/scripts/generate-project.mjs" "<name>" "<dest>" "<template>"
 ```
 
-`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the UI bundle), `scripts/`, `config/`, and `README.md`. See the framework reference from Step 1 for the specific bundle contents. If `sfdx-project.json` is missing or is one level down in `$DEST/$NAME/`, the flatten did not run — re-check before continuing.
+The script prints `OK: project root landed at <dest> (...)` and exits 0 on success. It exits non-zero (with a clear stderr message) if `sf template generate project` fails, the generated project has no `sfdx-project.json`, or the flatten didn't leave a valid project root — stop and surface the failure rather than continuing.
+
+`sfdx-project.json` must sit at `$DEST/sfdx-project.json`. The project also contains `package.json`, `force-app/main/default/uiBundles/$NAME/` (the UI bundle), `scripts/`, `config/`, and `README.md`. See the framework reference from Step 1 for the specific bundle contents.
 
 ## Step 3: Install dependencies (you do this — do NOT hand off uninstalled)
 
@@ -84,26 +67,17 @@ There are **multiple** `package.json` files, each needing its own install:
 - the **project root** (`$DEST/package.json`), and
 - the **UI bundle** dir under `$DEST/force-app/main/default/uiBundles/$NAME/` — this holds the toolchain the preview server loads, so it must have `node_modules` too.
 
-```sh
-# 1. project root ($DEST was set in Step 2)
-( cd "$DEST" && npm install )
+`<SKILL_DIR>/scripts/install-deps.mjs` runs `npm install` for the root and for every UI bundle that has a `package.json` (via Node's `child_process` with an explicit `cwd` — no `cd &&` shell chaining), then verifies `node_modules` landed everywhere it installed:
 
-# 2. each UI bundle
-for b in "$DEST"/force-app/main/default/uiBundles/*/; do
-  [ -f "$b/package.json" ] && ( cd "$b" && npm install )
-done
+```sh
+node "<SKILL_DIR>/scripts/install-deps.mjs" "<dest>"
 ```
 
-> First-run install of the bundle is the heavy step; expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
+Substitute the literal `$DEST` value from Step 2 for `<dest>`. The script prints `OK: all dependencies installed.` and exits 0 on success; it exits non-zero with a listed summary of which install(s) failed otherwise. First-run install of the bundle is the heavy step; expect a short wait. If an install fails, surface it — don't hand off a half-installed project.
 
 ## Step 4: Confirm and hand off
 
-Verify the project landed and is installed:
-
-```sh
-ls "$DEST" # sfdx-project.json, package.json, force-app/, scripts/, README.md ...
-ls "$DEST"/force-app/main/default/uiBundles/*/node_modules >/dev/null && echo "bundle deps installed"
-```
+`install-deps.mjs` already prints a verification summary (root + each UI bundle's `node_modules`) as part of Step 3. To look around the generated project yourself, use your own file-listing/read tools rather than a shell `ls` — that works identically regardless of the underlying OS shell.
 
 The project is now ready to develop and deploy. If there's a `README.md` in the template, take a look at it to see if there is any extra step or guidance for the user.
 
@@ -113,4 +87,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.

package/skills/experience-ui-bundle-project-generate/scripts/flatten-project.mjs

@@ -10,24 +10,46 @@
 // — only the paths the template ships get replaced. The per-entry rmSync + renameSync is what
 // guarantees the template's files win on conflict (including a file-vs-directory type mismatch).
 // Requires Node ≥ 16.7 for rmSync.
+//
+// Always invoke via `node` (never as a bare executable) so this works on Windows cmd/PowerShell
+// as well as macOS/Linux/Git Bash. Uses fs/path APIs only — no shell-out — so path separators and
+// move semantics are correct on every OS.
 
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-const [src, dest] = process.argv.slice(2);
+export function flattenProject(src, dest) {
+  if (!fs.existsSync(path.join(src, "sfdx-project.json"))) {
+    throw new Error("generated project has no sfdx-project.json: " + src);
+  }
 
-if (!src || !dest) {
-  console.error("usage: node <skill_dir>/scripts/flatten-project.mjs <srcDir> <destDir>");
-  process.exit(1);
+  for (const entry of fs.readdirSync(src)) {
+    const target = path.join(dest, entry);
+    fs.rmSync(target, { recursive: true, force: true });
+    fs.renameSync(path.join(src, entry), target);
+  }
 }
 
-if (!fs.existsSync(path.join(src, "sfdx-project.json"))) {
-  console.error("generated project has no sfdx-project.json: " + src);
-  process.exit(1);
+function main() {
+  const [src, dest] = process.argv.slice(2);
+
+  if (!src || !dest) {
+    console.error("usage: node <skill_dir>/scripts/flatten-project.mjs <srcDir> <destDir>");
+    process.exit(1);
+  }
+
+  try {
+    flattenProject(src, dest);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
 }
 
-for (const entry of fs.readdirSync(src)) {
-  const target = path.join(dest, entry);
-  fs.rmSync(target, { recursive: true, force: true });
-  fs.renameSync(path.join(src, entry), target);
+// Only run as a CLI when invoked directly (not when imported by generate-project.mjs).
+// pathToFileURL handles Windows drive letters/backslashes correctly (a manual
+// `file://${path}` string would not).
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
 }

package/skills/experience-ui-bundle-project-generate/scripts/generate-project.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Generate a `sf template generate project` starter and flatten it so the
+// contents land directly at the target root (no `<name>/` wrapper subfolder).
+//
+// Usage: node <skill_dir>/scripts/generate-project.mjs <name> <dest> <template>
+//   <name>     — project name passed to `sf template generate project --name`
+//   <dest>     — target root directory the contents should land in
+//                (so sfdx-project.json sits at <dest>/sfdx-project.json)
+//   <template> — the `--template` flag value from the chosen framework reference
+//
+// Always invoke via `node` (never as a bare executable, and never wrap this
+// in a bash/cmd/PowerShell script) so this works on Windows cmd/PowerShell
+// as well as macOS/Linux/Git Bash. Pass <name>/<dest>/<template> as literal
+// argv values — do not rely on shell variable assignment/interpolation
+// (`$VAR` / `%VAR%` / `$env:VAR` differ per shell).
+//
+// Runs `sf` via spawnSync with shell:true so the platform's own shell
+// resolves the CLI shim correctly (on Windows, globally-installed CLIs are
+// usually `.cmd`/`.ps1` wrappers that spawn() cannot find without a shell).
+//
+// Exit 0 on success (project landed at <dest>).
+// Exit 1 if `sf template generate project` fails, the generated project has
+// no sfdx-project.json, or the flatten didn't result in a valid project root.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { flattenProject } from "./flatten-project.mjs";
+
+const [name, dest, template] = process.argv.slice(2);
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+if (!name || !dest || !template) {
+  fail("usage: node <skill_dir>/scripts/generate-project.mjs <name> <dest> <template>");
+}
+
+fs.mkdirSync(dest, { recursive: true });
+
+const result = spawnSync(
+  "sf",
+  ["template", "generate", "project", "--name", name, "--template", template, "--output-dir", dest],
+  { stdio: "inherit", shell: true },
+);
+
+if (result.error) {
+  fail(`ERROR: failed to run "sf template generate project": ${result.error.message}`);
+}
+if (result.status !== 0) {
+  process.exit(result.status ?? 1);
+}
+
+const srcDir = path.join(dest, name);
+
+if (!fs.existsSync(path.join(srcDir, "sfdx-project.json"))) {
+  fail(`ERROR: generated project has no sfdx-project.json: ${srcDir}`);
+}
+
+try {
+  flattenProject(srcDir, dest);
+} catch (err) {
+  fail(`ERROR: ${err.message}`);
+}
+
+// Remove the now-empty (or leftover) generated subfolder.
+fs.rmSync(srcDir, { recursive: true, force: true });
+
+const destProjectFile = path.join(dest, "sfdx-project.json");
+if (!fs.existsSync(destProjectFile)) {
+  fail(`FAILED: sfdx-project.json not found at ${destProjectFile} — flatten did not run correctly`);
+}
+
+console.log(`OK: project root landed at ${dest} (${destProjectFile})`);
+process.exit(0);

package/skills/experience-ui-bundle-project-generate/scripts/install-deps.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Install dependencies for a generated UI bundle starter project: the
+// project root `package.json`, plus each `package.json` under
+// force-app/main/default/uiBundles/*/ (the toolchain the preview server
+// loads). Then verify node_modules landed everywhere it was installed.
+//
+// Usage: node <skill_dir>/scripts/install-deps.mjs <dest>
+//   <dest> — the project root (same value passed to generate-project.mjs)
+//
+// Always invoke via `node` (never as a bare executable, and never wrap this
+// in a bash/cmd/PowerShell script) so this works on Windows cmd/PowerShell
+// as well as macOS/Linux/Git Bash. Runs `npm install` via spawnSync with an
+// explicit `cwd` (no `cd &&` subshell chaining) and shell:true so the
+// platform's own shell resolves the `npm` CLI shim correctly.
+//
+// Exit 0 if every install succeeded (or there was nothing to install).
+// Exit 1 with a summary of which installs failed — surface it, don't hand
+// off a half-installed project.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const [dest] = process.argv.slice(2);
+
+if (!dest) {
+  console.error("usage: node <skill_dir>/scripts/install-deps.mjs <dest>");
+  process.exit(1);
+}
+
+function npmInstall(cwd) {
+  console.log(`Running "npm install" in ${cwd} ...`);
+  const result = spawnSync("npm", ["install"], { cwd, stdio: "inherit", shell: true });
+  if (result.error) {
+    return `${cwd}: ${result.error.message}`;
+  }
+  if (result.status !== 0) {
+    return `${cwd}: npm install exited with code ${result.status}`;
+  }
+  return null;
+}
+
+const failures = [];
+
+// 1. Project root.
+if (fs.existsSync(path.join(dest, "package.json"))) {
+  const failure = npmInstall(dest);
+  if (failure) failures.push(failure);
+} else {
+  console.error(`ERROR: no package.json found at project root: ${dest}`);
+  failures.push(`${dest}: missing package.json`);
+}
+
+// 2. Each UI bundle.
+const bundlesDir = path.join(dest, "force-app", "main", "default", "uiBundles");
+const bundleDirs = fs.existsSync(bundlesDir)
+  ? fs
+      .readdirSync(bundlesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(bundlesDir, entry.name))
+  : [];
+
+for (const bundleDir of bundleDirs) {
+  if (fs.existsSync(path.join(bundleDir, "package.json"))) {
+    const failure = npmInstall(bundleDir);
+    if (failure) failures.push(failure);
+  }
+}
+
+// 3. Verify node_modules landed everywhere it was installed.
+console.log("\nVerifying installs:");
+let allInstalled = true;
+if (fs.existsSync(path.join(dest, "package.json"))) {
+  const ok = fs.existsSync(path.join(dest, "node_modules"));
+  console.log(`  ${ok ? "OK" : "MISSING"}: ${path.join(dest, "node_modules")}`);
+  allInstalled = allInstalled && ok;
+}
+for (const bundleDir of bundleDirs) {
+  if (fs.existsSync(path.join(bundleDir, "package.json"))) {
+    const ok = fs.existsSync(path.join(bundleDir, "node_modules"));
+    console.log(`  ${ok ? "OK" : "MISSING"}: ${path.join(bundleDir, "node_modules")}`);
+    allInstalled = allInstalled && ok;
+  }
+}
+
+if (failures.length > 0 || !allInstalled) {
+  console.error("\nFAILED: one or more installs did not complete:");
+  for (const failure of failures) {
+    console.error(`  - ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log("\nOK: all dependencies installed.");
+process.exit(0);

package/skills/integration-connectivity-connected-app-configure/SKILL.md

@@ -38,8 +38,8 @@ Use this skill when the user needs **OAuth app configuration** in Salesforce: Co
 
 **Out of scope — delegate elsewhere:**
 - Configuring Named Credentials or runtime callouts → [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md)
-- Deploying metadata to orgs → [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md)
-- Writing Apex token-handling code → [platform-apex-generate](../platform-apex-generate/SKILL.md)
+- Deploying metadata to orgs → the `platform-metadata-deploy` skill
+- Writing Apex token-handling code → the `platform-apex-generate` skill
 
 ---
 
@@ -206,8 +206,8 @@ Score: <x>/120
 | Need | Delegate to | Reason |
 |---|---|---|
 | Named Credential / callout runtime config | [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md) | runtime integration setup |
-| Deploy app metadata | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | org validation and deployment |
-| Apex token or refresh handling | [platform-apex-generate](../platform-apex-generate/SKILL.md) | implementation logic |
+| Deploy app metadata | `platform-metadata-deploy` skill | org validation and deployment |
+| Apex token or refresh handling | `platform-apex-generate` skill | implementation logic |
 
 ---
 
@@ -237,4 +237,4 @@ Score: <x>/120
 | `references/security-checklist.md` | Step 4 — full 120-point security scoring checklist |
 | `references/testing-validation-guide.md` | Step 5 — pre-deployment validation and testing guide |
 | `references/migration-guide.md` | When migrating from Connected App to ECA patterns |
-| `references/example-usage.md` | Full end-to-end examples for common OAuth scenarios |
+| `references/example-usage.md` | Full end-to-end examples for common OAuth scenarios |

package/skills/integration-connectivity-generate/SKILL.md

@@ -39,9 +39,9 @@ Use `integration-connectivity-generate` when the work involves:
 
 Delegate elsewhere when the user is:
 - configuring the OAuth app itself → [integration-connectivity-connected-app-configure](../integration-connectivity-connected-app-configure/SKILL.md)
-- writing Apex-only business logic → [platform-apex-generate](../platform-apex-generate/SKILL.md)
-- deploying metadata → [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md)
-- importing/exporting data → [platform-data-manage](../platform-data-manage/SKILL.md)
+- writing Apex-only business logic → the `platform-apex-generate` skill
+- deploying metadata → the `platform-metadata-deploy` skill
+- importing/exporting data → the `platform-data-manage` skill
 
 ---
 
@@ -93,9 +93,9 @@ Check:
 
 ### 5. Hand off deployment or implementation details
 Use:
-- [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) for deployment
-- [platform-apex-generate](../platform-apex-generate/SKILL.md) for deeper service / retry code
-- [automation-flow-generate](../automation-flow-generate/SKILL.md) for declarative HTTP callout orchestration
+- the `platform-metadata-deploy` skill for deployment
+- the `platform-apex-generate` skill for deeper service / retry code
+- the `automation-flow-generate` skill for declarative HTTP callout orchestration
 
 ---
 
@@ -142,10 +142,10 @@ Next step: <deploy, register, test, or implement>
 | Need | Delegate to | Reason |
 |---|---|---|
 | OAuth app setup | [integration-connectivity-connected-app-configure](../integration-connectivity-connected-app-configure/SKILL.md) | consumer key / cert / app config |
-| advanced callout service code | [platform-apex-generate](../platform-apex-generate/SKILL.md) | Apex implementation |
-| declarative HTTP callout / Flow wrapper | [automation-flow-generate](../automation-flow-generate/SKILL.md) | Flow orchestration |
-| deploy integration metadata | [platform-metadata-deploy](../platform-metadata-deploy/SKILL.md) | validation and rollout |
-| use integration from Agentforce | [agentforce-generate](../agentforce-generate/SKILL.md) | agent action composition |
+| advanced callout service code | `platform-apex-generate` skill | Apex implementation |
+| declarative HTTP callout / Flow wrapper | `automation-flow-generate` skill | Flow orchestration |
+| deploy integration metadata | `platform-metadata-deploy` skill | validation and rollout |
+| use integration from Agentforce | `agentforce-generate` skill | agent action composition |
 
 ---
 

package/skills/integration-connectivity-generate/scripts/configure-named-credential.sh

@@ -190,14 +190,14 @@ try {
     // Create the credential (first-time setup)
     ConnectApi.NamedCredentials.createCredential(newCredentials);
     System.debug('✓ External Credential configured successfully!');
-    System.debug('Principal: $PRINCIPAL_NAME');
+    System.debug('Principal: $PRINCIPAL_NAME_ESCAPED');
 } catch (Exception e) {
     // If already exists, try patching instead
     if (e.getMessage().contains('already exists')) {
         try {
             ConnectApi.NamedCredentials.patchCredential(newCredentials);
             System.debug('✓ External Credential updated successfully!');
-            System.debug('Principal: $PRINCIPAL_NAME');
+            System.debug('Principal: $PRINCIPAL_NAME_ESCAPED');
         } catch (Exception e2) {
             System.debug('✗ Error updating credential: ' + e2.getMessage());
             throw e2;