@salesforce/afv-skills 1.57.0 → 1.59.0

package/skills/experience-ui-bundle-app-coordinate/scripts/check-dangling-refs.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// Verify no surviving file still imports/references a file deleted during
+// scaffold pruning.
+// Usage: node check-dangling-refs.mjs <deleted-basename> [<deleted-basename> ...]
+//   <deleted-basename> is the file name without extension, e.g. "codegen" for
+//   codegen.yml, "graphqlClient" for src/api/graphqlClient.ts, "useAsyncData"
+//   for the deleted hook.
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash. Quote each
+// <deleted-basename> argument.
+//
+// Exit 0 if no dangling references found, exit 1 with error message(s) if
+// any are found.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
+const UIBUNDLES_DIR = path.join("force-app", "main", "default", "uiBundles");
+
+// Filesystem read errors encountered while walking the bundle or reading a
+// file. A dangling-reference scan that could not read part of the tree has NOT
+// proven the reference is gone, so any entry here must turn a would-be SUCCESS
+// into a non-zero exit (see the end of the script).
+const ioErrors = [];
+
+function findBundleDir() {
+  let entries;
+  try {
+    entries = fs.readdirSync(UIBUNDLES_DIR, { withFileTypes: true });
+  } catch {
+    // uiBundles dir absent/unreadable: return "" so the caller emits an explicit
+    // "No UI bundle directory found" error and exits non-zero. This is a handled,
+    // expected case (e.g. a fresh project), not a silently-swallowed failure.
+    return "";
+  }
+  const dirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+  return dirs.length > 0 ? path.join(UIBUNDLES_DIR, dirs[0]) : "";
+}
+
+function collectFiles(dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    // A subdirectory we cannot list may hide a surviving reference. Record it so
+    // the run fails rather than reporting an untrustworthy SUCCESS.
+    ioErrors.push(`could not read directory '${dir}': ${err.message}`);
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (EXCLUDE_DIRS.has(entry.name)) continue;
+      collectFiles(full, out);
+    } else if (entry.isFile()) {
+      out.push(full);
+    }
+  }
+}
+
+const basenames = process.argv.slice(2);
+
+if (basenames.length === 0) {
+  console.error(
+    "ERROR: check-dangling-refs.mjs requires at least one deleted-file basename as an argument",
+  );
+  process.exit(1);
+}
+
+const bundleDir = findBundleDir();
+
+if (!bundleDir) {
+  console.error(`ERROR: No UI bundle directory found in ${UIBUNDLES_DIR}${path.sep}`);
+  process.exit(1);
+}
+
+const files = [];
+collectFiles(bundleDir, files);
+
+let foundDangling = false;
+
+for (const basename of basenames) {
+  const matches = [];
+  for (const file of files) {
+    let content;
+    try {
+      content = fs.readFileSync(file, "utf8");
+    } catch (err) {
+      // Could not read a surviving file — record and skip. We cannot confirm it
+      // is free of the deleted reference, so the run must not report SUCCESS.
+      ioErrors.push(`could not read file '${file}': ${err.message}`);
+      continue;
+    }
+    if (content.includes(basename)) {
+      matches.push(file);
+    }
+  }
+
+  if (matches.length > 0) {
+    foundDangling = true;
+    console.error(`ERROR: Dangling reference to deleted file '${basename}' found in:`);
+    for (const match of matches) {
+      console.error(`  - ${match}`);
+    }
+  }
+}
+
+if (foundDangling) {
+  process.exit(1);
+}
+
+// A read failure means the scan was incomplete — do not claim SUCCESS.
+if (ioErrors.length > 0) {
+  console.error(
+    "ERROR: dangling-reference scan is incomplete — some paths could not be read:",
+  );
+  for (const e of ioErrors) {
+    console.error(`  - ${e}`);
+  }
+  console.error(
+    "Resolve the read errors above and re-run; not reporting SUCCESS on an incomplete scan.",
+  );
+  process.exit(1);
+}
+
+console.log(`SUCCESS: No dangling references found for: ${basenames.join(" ")}`);
+process.exit(0);

package/skills/experience-ui-bundle-app-coordinate/scripts/check-hosting-target.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Check which hosting target is configured in .uibundle-meta.xml files.
+// Usage: node check-hosting-target.mjs
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Prints "ExperienceSite" or "CustomApplication" to stdout and exits 0 on
+// success. Exits 1 with an error message if no .uibundle-meta.xml files
+// are found, or none declare a valid target.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
+
+function findMetaFiles(dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (EXCLUDE_DIRS.has(entry.name)) continue;
+      findMetaFiles(full, out);
+    } else if (entry.isFile() && entry.name.endsWith(".uibundle-meta.xml")) {
+      out.push(full);
+    }
+  }
+}
+
+const metaFiles = [];
+findMetaFiles(".", metaFiles);
+
+if (metaFiles.length === 0) {
+  console.error("ERROR: No .uibundle-meta.xml files found");
+  process.exit(1);
+}
+
+const contents = metaFiles.map((f) => {
+  try {
+    return fs.readFileSync(f, "utf8");
+  } catch {
+    return "";
+  }
+});
+
+if (contents.some((c) => c.includes("<target>ExperienceSite</target>"))) {
+  console.log("ExperienceSite");
+  process.exit(0);
+}
+
+if (contents.some((c) => c.includes("<target>CustomApplication</target>"))) {
+  console.log("CustomApplication");
+  process.exit(0);
+}
+
+console.error("ERROR: No valid hosting target found in .uibundle-meta.xml");
+process.exit(1);

package/skills/experience-ui-bundle-app-coordinate/scripts/check-phase-1-complete.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Verify Phase 1 (Scaffolding) completed successfully.
+// Usage: node check-phase-1-complete.mjs
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Exit 0 if complete, exit 1 with an error message if incomplete.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const UIBUNDLES_DIR = path.join("force-app", "main", "default", "uiBundles");
+
+function findBundleDir() {
+  let entries;
+  try {
+    entries = fs.readdirSync(UIBUNDLES_DIR, { withFileTypes: true });
+  } catch {
+    return "";
+  }
+  const dirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+  return dirs.length > 0 ? path.join(UIBUNDLES_DIR, dirs[0]) : "";
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const bundleDir = findBundleDir();
+
+if (!bundleDir) {
+  fail(
+    `ERROR: Phase 1 incomplete: No UI bundle directory found in ${UIBUNDLES_DIR}${path.sep}`,
+  );
+}
+
+if (!fs.existsSync(path.join(bundleDir, "src"))) {
+  fail(`ERROR: Phase 1 incomplete: No src/ directory found in ${bundleDir}`);
+}
+
+const metaFiles = fs
+  .readdirSync(bundleDir)
+  .filter((name) => name.endsWith(".uibundle-meta.xml"));
+
+if (metaFiles.length === 0) {
+  fail(`ERROR: Phase 1 incomplete: No .uibundle-meta.xml file found in ${bundleDir}`);
+}
+
+const hasTarget = metaFiles.some((name) => {
+  try {
+    return fs.readFileSync(path.join(bundleDir, name), "utf8").includes("<target>");
+  } catch {
+    return false;
+  }
+});
+
+if (!hasTarget) {
+  fail("ERROR: Phase 1 incomplete: .uibundle-meta.xml missing <target> element");
+}
+
+if (!fs.existsSync(path.join(bundleDir, "package.json"))) {
+  fail(`ERROR: Phase 1 incomplete: No package.json found in ${bundleDir}`);
+}
+
+console.log("SUCCESS: Phase 1 complete: Scaffold verified");
+process.exit(0);

package/skills/experience-ui-bundle-app-coordinate/scripts/check-phase-4-complete.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Verify Phase 4 (UI) completed successfully.
+// Usage: node check-phase-4-complete.mjs
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Exit 0 if complete, exit 1 with an error message if incomplete.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const UIBUNDLES_DIR = path.join("force-app", "main", "default", "uiBundles");
+
+function findBundleDir() {
+  let entries;
+  try {
+    entries = fs.readdirSync(UIBUNDLES_DIR, { withFileTypes: true });
+  } catch {
+    return "";
+  }
+  const dirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+  return dirs.length > 0 ? path.join(UIBUNDLES_DIR, dirs[0]) : "";
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function findTsxFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...findTsxFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith(".tsx")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+const bundleDir = findBundleDir();
+
+if (!bundleDir) {
+  fail("ERROR: Phase 4 cannot run: No UI bundle directory found (Phase 1 not complete)");
+}
+
+// Check Phase 1 scaffold prerequisites
+const packageJsonPath = path.join(bundleDir, "package.json");
+if (!fs.existsSync(packageJsonPath)) {
+  fail("ERROR: Phase 4 cannot run: No package.json found (Phase 1 not complete)");
+}
+
+let packageJsonContent = "";
+try {
+  packageJsonContent = fs.readFileSync(packageJsonPath, "utf8");
+} catch {
+  packageJsonContent = "";
+}
+
+if (!packageJsonContent.includes('"react"')) {
+  fail("ERROR: Phase 4 cannot run: React dependencies not installed in package.json");
+}
+
+// Check Phase 4 completion
+if (!fs.existsSync(path.join(bundleDir, "src", "App.tsx"))) {
+  fail(`ERROR: Phase 4 incomplete: No App.tsx found in ${path.join(bundleDir, "src")}${path.sep}`);
+}
+
+const pagesDir = path.join(bundleDir, "src", "pages");
+if (!fs.existsSync(pagesDir) || !fs.statSync(pagesDir).isDirectory()) {
+  fail(`ERROR: Phase 4 incomplete: No pages/ directory found in ${path.join(bundleDir, "src")}${path.sep}`);
+}
+
+if (findTsxFiles(pagesDir).length === 0) {
+  fail("ERROR: Phase 4 incomplete: No .tsx files found in pages/ directory");
+}
+
+if (!fs.existsSync(path.join(bundleDir, "dist", "index.html"))) {
+  fail("ERROR: Phase 4 incomplete: No dist/index.html found (build not complete)");
+}
+
+console.log("SUCCESS: Phase 4 complete: UI verified");
+process.exit(0);

package/skills/experience-ui-bundle-app-coordinate/scripts/check-phase-6-ready.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Verify Phase 6 (Deployment) prerequisites are met.
+// Usage: node check-phase-6-ready.mjs
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Exit 0 if ready, exit 1 with an error message if not ready.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const UIBUNDLES_DIR = path.join("force-app", "main", "default", "uiBundles");
+
+function findBundleDir() {
+  let entries;
+  try {
+    entries = fs.readdirSync(UIBUNDLES_DIR, { withFileTypes: true });
+  } catch {
+    return "";
+  }
+  const dirs = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+  return dirs.length > 0 ? path.join(UIBUNDLES_DIR, dirs[0]) : "";
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+const bundleDir = findBundleDir();
+
+if (!bundleDir) {
+  fail("ERROR: Phase 6 cannot run: No UI bundle directory found (Phase 1 not complete)");
+}
+
+// Check build artifact exists
+if (!fs.existsSync(path.join(bundleDir, "dist", "index.html"))) {
+  fail("ERROR: Phase 6 cannot run: No dist/index.html found (Phase 4 build not complete)");
+}
+
+// Check org authentication
+// `shell: true` resolves `sf`/`sf.cmd` across macOS/Linux/Git Bash and native
+// Windows shells alike.
+const orgDisplay = spawnSync("sf", ["org", "display", "--json"], {
+  shell: true,
+  stdio: "ignore",
+});
+
+if (orgDisplay.status !== 0) {
+  fail("ERROR: Phase 6 cannot run: No authenticated org found (run: sf org login web)");
+}
+
+// Check hosting target is set
+const metaFiles = fs
+  .readdirSync(bundleDir)
+  .filter((name) => name.endsWith(".uibundle-meta.xml"));
+
+const hasTarget = metaFiles.some((name) => {
+  try {
+    return fs.readFileSync(path.join(bundleDir, name), "utf8").includes("<target>");
+  } catch {
+    return false;
+  }
+});
+
+if (!hasTarget) {
+  fail(
+    "ERROR: Phase 6 cannot run: .uibundle-meta.xml missing <target> element (Phase 1 not complete)",
+  );
+}
+
+console.log("SUCCESS: Phase 6 ready: All deployment prerequisites met");
+process.exit(0);

package/skills/experience-ui-bundle-app-coordinate/scripts/check-prerequisites.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Check prerequisites for UI Bundle app building.
+// Usage: node check-prerequisites.mjs
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Exit 0 if all prerequisites are met, exit 1 with an error message if any
+// are missing.
+
+const [major] = process.versions.node.split(".").map(Number);
+
+if (!Number.isFinite(major) || major < 20) {
+  console.error(
+    `ERROR: Node.js version ${process.versions.node} detected. Requires >= 20.x`,
+  );
+  process.exit(1);
+}
+
+console.log(`SUCCESS: Node.js v${process.versions.node} meets the >= 20.x requirement`);
+process.exit(0);

package/skills/experience-ui-bundle-app-coordinate/scripts/check-sfdx-project.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Check if sfdx-project.json exists and is valid JSON.
+// Usage: node check-sfdx-project.mjs
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Exit 0 if sfdx-project.json exists and parses as JSON, exit 1 with an
+// error message otherwise.
+
+import fs from "node:fs";
+
+const SFDX_PROJECT = "sfdx-project.json";
+
+if (!fs.existsSync(SFDX_PROJECT)) {
+  console.error("ERROR: sfdx-project.json not found");
+  process.exit(1);
+}
+
+try {
+  JSON.parse(fs.readFileSync(SFDX_PROJECT, "utf8"));
+} catch {
+  console.error("ERROR: sfdx-project.json is not valid JSON");
+  process.exit(1);
+}
+
+console.log("sfdx-project.json is valid");
+process.exit(0);

package/skills/experience-ui-bundle-custom-app-generate/SKILL.md

@@ -8,6 +8,8 @@ metadata:
   relatedSkills:
     - "platform-custom-application-generate"
   cliTools:
+    - tool: ["node"]
+      semver: ">=18.0.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
   mcpTools:
@@ -76,7 +78,7 @@ Use the default template in the doc below. Values in `{braces}` are resolved pro
 ### Step 5: Update UI Bundle Meta XML
 This step edits an **existing** file — it never creates a new one. `UIBundle` is a bundle-style metadata type: its meta XML normally lives inside its own folder at `uiBundles/{appName}/{appName}.uibundle-meta.xml`, alongside the bundle's other source files (e.g. `index.html`, `src/`). Some older or hand-authored projects may instead have it at the flat path `uiBundles/{appName}.uibundle-meta.xml` (no subfolder).
 
-Run `scripts/resolve-uibundle-path.sh "{appName}"` — it prints the path of the existing meta XML (preferring the nested layout, falling back to the flat layout). Edit that exact file in place; do not create a second file at the other path or migrate it to a different layout as part of this skill.
+Run `node scripts/resolve-uibundle-path.mjs "{appName}"` — it prints the path of the existing meta XML (preferring the nested layout, falling back to the flat layout). Always invoke via `node` (never as a bare executable) so this works on Windows as well as macOS/Linux. Edit that exact file in place; do not create a second file at the other path or migrate it to a different layout as part of this skill.
 
 If Step 2 confirmed the `target` field exists on `UIBundle`, add `<target>CustomApplication</target>` inside the existing `<UIBundle>` element of that file, preserving every other existing element and value untouched (skip this step entirely if the field doesn't exist in the org's API version — do not create the file or add `<target>` in that case).
 

package/skills/experience-ui-bundle-custom-app-generate/scripts/resolve-uibundle-path.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Resolve the existing path of a UIBundle's meta XML file.
+//
+// UIBundle metadata may live at either the nested bundle-style path
+// (uiBundles/{appName}/{appName}.uibundle-meta.xml) or, in older/hand-authored
+// projects, the flat path (uiBundles/{appName}.uibundle-meta.xml). This script
+// performs the deterministic file-existence check and prints whichever path
+// already exists, preferring the nested layout.
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+//
+// Usage: node scripts/resolve-uibundle-path.mjs <appName>
+//
+// Exit 0: existing meta XML found — its path is printed to stdout.
+// Exit 1: appName argument missing, or no .uibundle-meta.xml found for it.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const APP = process.argv[2] ?? "";
+
+if (!APP) {
+  console.error("ERROR: appName argument is required");
+  process.exit(1);
+}
+
+const NESTED = path.join("uiBundles", APP, `${APP}.uibundle-meta.xml`);
+const FLAT = path.join("uiBundles", `${APP}.uibundle-meta.xml`);
+
+if (fs.existsSync(NESTED) && fs.statSync(NESTED).isFile()) {
+  console.log(NESTED);
+  process.exit(0);
+} else if (fs.existsSync(FLAT) && fs.statSync(FLAT).isFile()) {
+  console.log(FLAT);
+  process.exit(0);
+} else {
+  console.error(`ERROR: no .uibundle-meta.xml found for ${APP}`);
+  process.exit(1);
+}

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

@@ -10,6 +10,8 @@ metadata:
     - "experience-ui-bundle-metadata-generate"
     - "experience-ui-bundle-salesforce-data-access"
   cliTools:
+    - tool: ["node"]
+      semver: ">=18.0.0"
     - tool: ["npm"]
       semver: ">=8.0.0"
     - tool: ["npx"]
@@ -22,7 +24,7 @@ metadata:
 
 ## Resolve the Bundle Directory
 
-**MUST** run `scripts/resolve-ui-bundle.sh [project-root]` before applying any rule below or writing any file — an ad-hoc `find`/`ls` is not a substitute; it does not enforce the exit-code gate below. It reads `sfdx-project.json`'s `packageDirectories[0].path` (does not assume `force-app` — the source path is configurable) and looks under `<sourceDir>/main/default/uiBundles/`:
+**MUST** run `node scripts/resolve-ui-bundle.mjs [project-root]` before applying any rule below or writing any file — an ad-hoc `find`/`ls` is not a substitute; it does not enforce the exit-code gate below. Always invoke via `node` (never as a bare executable) so this works on Windows as well as macOS/Linux. It reads `sfdx-project.json`'s `packageDirectories[0].path` (does not assume `force-app` — the source path is configurable) and looks under `<sourceDir>/main/default/uiBundles/`:
 
 - **Exit 0**, bundle path printed to stdout: exactly one bundle directory found — that is the bundle directory. Use that exact directory name; never substitute a different name (e.g. a generic "AcmePortal" example from a prompt template) for the one actually printed.
 - **Exit 2**, candidates printed to stderr: multiple `uiBundles/*` subdirectories exist — do not guess, and do not write to any of them, or to a bundle name not in the printed list. Ask the user which app/bundle they mean before editing or running any command.
@@ -32,10 +34,10 @@ Run all `npm`/lint/build/dev commands from inside the resolved bundle directory,
 
 ## Preconditions
 
-Before applying any rule below, confirm this is an existing, scaffolded UI bundle: **MUST** run `scripts/check-preconditions.sh <bundle-dir>` with the directory `resolve-ui-bundle.sh` printed.
+Before applying any rule below, confirm this is an existing, scaffolded UI bundle: **MUST** run `node scripts/check-preconditions.mjs <bundle-dir>` with the directory `resolve-ui-bundle.mjs` printed.
 
 - **Single-bundle (exit 0) case**: run it once, on that bundle.
-- **Multi-bundle (exit 2) case**: do not run it yet — first ask the user which app/bundle they mean, per the Resolve step above. Once the user names the bundle, run `check-preconditions.sh` on that one bundle only. Never run it against multiple candidates speculatively before the user has chosen — that means touching/inspecting bundles the user didn't ask about.
+- **Multi-bundle (exit 2) case**: do not run it yet — first ask the user which app/bundle they mean, per the Resolve step above. Once the user names the bundle, run `check-preconditions.mjs` on that one bundle only. Never run it against multiple candidates speculatively before the user has chosen — that means touching/inspecting bundles the user didn't ask about.
 - **Exit 0**: the bundle has `src/appLayout.tsx`, `src/routes.tsx`, and `src/components/ui/` — proceed.
 - **Exit 1**, missing pieces listed: this is a fresh SFDX project, a non-UI-bundle React project, or a partially-scaffolded bundle — **stop**. Do not fall back to generic React knowledge (e.g. `react-router-dom`, a hardcoded basename, or raw HTML), and do not hand-write `appLayout.tsx`/`routes.tsx`/a page/a component to "fill in" the missing scaffold, even for a casual, vague, or urgent-sounding request ("just change the header", "make the background blue"). Tell the user the bundle isn't scaffolded yet and direct them to `experience-ui-bundle-app-coordinate` (or `experience-ui-bundle-metadata-generate`) to scaffold it first. If, after the user names their intended bundle, that one turns out to be unscaffolded, stop and redirect for it — do not silently switch to scaffolding a different candidate instead.
 
@@ -80,7 +82,7 @@ When making any change that affects navigation, header, footer, sidebar, theme,
 
 `index.html` lives at the bundle root (not under `src/`), but it is still in scope for this skill whenever branding or the app name changes — the leftover `<title>React App</title>` / `Vite + React` boilerplate is a common ship-blocker that `npm run lint`/`npm run build` never catches.
 
-Before finishing, confirm: Did I update `appLayout.tsx` with real nav items and branding? Then run `scripts/verify-rules.sh` to check for residual boilerplate (see Verification below).
+Before finishing, confirm: Did I update `appLayout.tsx` with real nav items and branding? Then run `node scripts/verify-rules.mjs` to check for residual boilerplate (see Verification below).
 
 | What | Where |
 |------|-------|
@@ -191,7 +193,7 @@ Before completing, run all of the following from the resolved UI bundle director
 2. `npm run build` — must succeed.
 3. `npm run dev` (or the project's dev-server script) — confirm the app starts cleanly so the change is verified at runtime, not just at build time.
 
-**`lint`/`build` alone do not catch the highest-risk rules in this skill** — a wrong `react-router-dom` import, a hardcoded basename, an inline `style={{}}`, or a stray `lightning/*` import can all lint and build clean while breaking at runtime. After any change that touches routing, layout, styling, or module imports, run `scripts/verify-rules.sh <files-or-dirs-you-edited>`:
+**`lint`/`build` alone do not catch the highest-risk rules in this skill** — a wrong `react-router-dom` import, a hardcoded basename, an inline `style={{}}`, or a stray `lightning/*` import can all lint and build clean while breaking at runtime. After any change that touches routing, layout, styling, or module imports, run `node scripts/verify-rules.mjs <files-or-dirs-you-edited>`:
 
 - **Exit 0**: no violations found.
 - **Exit 1**, violations listed by rule and file: fix every one before considering the task complete, even if lint and build passed.

package/skills/experience-ui-bundle-frontend-generate/scripts/check-preconditions.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Verify a resolved UI bundle directory is actually scaffolded before any
+// rule in this skill applies.
+// Usage: node check-preconditions.mjs <bundle-dir>
+//   <bundle-dir> is the path printed by resolve-ui-bundle.mjs.
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash. Quote
+// <bundle-dir> so Windows paths and spaces survive the shell.
+//
+// Exit 0 if the bundle is scaffolded (src/appLayout.tsx, src/routes.tsx, and
+// src/components/ui/ all present).
+// Exit 1 with the missing pieces listed if the bundle is a fresh SFDX
+// project, a non-UI-bundle React project, or only partially scaffolded —
+// the caller must stop and redirect the user to
+// experience-ui-bundle-app-coordinate (or experience-ui-bundle-metadata-generate)
+// instead of falling back to generic React knowledge.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const BUNDLE_DIR = process.argv[2] ?? "";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+if (!BUNDLE_DIR) {
+  fail("ERROR: check-preconditions.mjs requires a valid bundle directory argument");
+}
+
+let isDir = false;
+try {
+  isDir = fs.statSync(BUNDLE_DIR).isDirectory();
+} catch {
+  isDir = false;
+}
+
+if (!isDir) {
+  fail("ERROR: check-preconditions.mjs requires a valid bundle directory argument");
+}
+
+const missing = [];
+if (!fs.existsSync(path.join(BUNDLE_DIR, "src", "appLayout.tsx"))) {
+  missing.push("src/appLayout.tsx");
+}
+if (!fs.existsSync(path.join(BUNDLE_DIR, "src", "routes.tsx"))) {
+  missing.push("src/routes.tsx");
+}
+const uiDir = path.join(BUNDLE_DIR, "src", "components", "ui");
+if (!fs.existsSync(uiDir) || !fs.statSync(uiDir).isDirectory()) {
+  missing.push("src/components/ui/");
+}
+
+if (missing.length > 0) {
+  console.error(`ERROR: ${BUNDLE_DIR} is not a scaffolded UI bundle. Missing:`);
+  for (const item of missing) {
+    console.error(`  - ${item}`);
+  }
+  console.error(
+    "Stop here. Tell the user the bundle isn't scaffolded yet and direct them to experience-ui-bundle-app-coordinate (or experience-ui-bundle-metadata-generate) to scaffold it first.",
+  );
+  process.exit(1);
+}
+
+console.log(
+  `SUCCESS: ${BUNDLE_DIR} is scaffolded (src/appLayout.tsx, src/routes.tsx, src/components/ui/ present)`,
+);
+process.exit(0);