@salesforce/templates 66.5.5 → 66.6.0

package/lib/templates/project/{reactb2x → reactexternalapp}/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.101.3",
+  "version": "1.114.0",
   "description": "Base SFDX project template",
-  "private": true,
-  "files": [
-    "dist"
-  ],
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
+    "sf-project-setup": "node scripts/sf-project-setup.mjs",
     "build": "echo 'No build required for base-sfdx-project'",
     "clean": "echo 'No clean required for base-sfdx-project'",
-    "lint": "eslint **/{aura,lwc}/**/*.js",
+    "lint": "eslint --no-error-on-unmatched-pattern **/{aura,lwc}/**/*.js",
     "test": "npm run test:unit",
     "test:coverage": "npm run test",
     "test:unit": "sfdx-lwc-jest -- --passWithNoTests",
@@ -22,13 +23,13 @@
     "setup": "node scripts/setup-cli.mjs"
   },
   "devDependencies": {
-    "@lwc/eslint-plugin-lwc": "^2.0.0",
+    "@lwc/eslint-plugin-lwc": "^3.3.0",
     "@prettier/plugin-xml": "^3.2.2",
-    "@salesforce/eslint-config-lwc": "^3.2.3",
-    "@salesforce/eslint-plugin-aura": "^2.0.0",
-    "@salesforce/eslint-plugin-lightning": "^1.0.0",
+    "@salesforce/eslint-config-lwc": "^4.1.0",
+    "@salesforce/eslint-plugin-aura": "^3.0.0",
+    "@salesforce/eslint-plugin-lightning": "^2.0.0",
     "@salesforce/sfdx-lwc-jest": "^7.0.1",
-    "eslint": "8.57.1",
+    "eslint": "^9.39.0",
     "eslint-plugin-import": "^2.25.4",
     "eslint-plugin-jest": "^28.8.1",
     "husky": "^9.1.5",

package/lib/templates/project/reactexternalapp/scripts/graphql-search.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipeline failures (-o pipefail)
+# graphql-search.sh — Look up one or more Salesforce entities in schema.graphql.
+#
+# Run from the SFDX project root (where schema.graphql lives):
+#   bash scripts/graphql-search.sh Account
+#   bash scripts/graphql-search.sh Account Contact Opportunity
+#
+# Pass a custom schema path with -s / --schema:
+#   bash scripts/graphql-search.sh -s /path/to/schema.graphql Account
+#   bash scripts/graphql-search.sh --schema ./other/schema.graphql Account Contact
+#
+# Output sections per entity:
+#   1. Type definition          — all fields and relationships
+#   2. Filter options           — <Entity>_Filter input (for `where:`)
+#   3. Sort options             — <Entity>_OrderBy input (for `orderBy:`)
+#   4. Create mutation wrapper  — <Entity>CreateInput
+#   5. Create mutation fields   — <Entity>CreateRepresentation (for create mutations)
+#   6. Update mutation wrapper  — <Entity>UpdateInput
+#   7. Update mutation fields   — <Entity>UpdateRepresentation (for update mutations)
+
+SCHEMA="./schema.graphql"
+
+# ── Argument parsing ─────────────────────────────────────────────────────────
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -s|--schema)
+      if [[ -z "${2-}" || "$2" == -* ]]; then
+        echo "ERROR: --schema requires a file path argument"
+        exit 1
+      fi
+      SCHEMA="$2"
+      shift 2
+      ;;
+    --)
+      shift
+      break
+      ;;
+    -*)
+      echo "ERROR: Unknown option: $1"
+      echo "Usage: bash $0 [-s <schema-path>] <EntityName> [EntityName2 ...]"
+      exit 1
+      ;;
+    *)
+      break
+      ;;
+  esac
+done
+
+if [ $# -eq 0 ]; then
+  echo "Usage: bash $0 [-s <schema-path>] <EntityName> [EntityName2 ...]"
+  echo "Example: bash $0 Account"
+  echo "Example: bash $0 Account Contact Opportunity"
+  echo "Example: bash $0 --schema /path/to/schema.graphql Account"
+  exit 1
+fi
+
+if [ ! -f "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql not found at $SCHEMA"
+  echo "  Make sure you are running from the SFDX project root, or pass the path explicitly:"
+  echo "    bash $0 --schema <path/to/schema.graphql> <EntityName>"
+  echo "  If the file is missing entirely, generate it from the webapp dir:"
+  echo "    cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
+  exit 1
+fi
+
+if [ ! -r "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql is not readable at $SCHEMA"
+  echo "  Check file permissions: ls -la $SCHEMA"
+  exit 1
+fi
+
+if [ ! -s "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql is empty at $SCHEMA"
+  echo "  Regenerate it from the webapp dir:"
+  echo "    cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
+  exit 1
+fi
+
+# ── Helper: extract lines from a grep match through the closing brace ────────
+# Prints up to MAX_LINES lines after (and including) the first match of PATTERN.
+# Uses a generous line count — blocks are always closed by a "}" line.
+
+extract_block() {
+  local label="$1"
+  local pattern="$2"
+  local max_lines="$3"
+
+  local match
+  local grep_exit=0
+  match=$(grep -nE "$pattern" "$SCHEMA" | head -1) || grep_exit=$?
+
+  if [ "$grep_exit" -eq 2 ]; then
+    echo "  ERROR: grep failed on pattern: $pattern" >&2
+    return 1
+  fi
+
+  if [ -z "$match" ]; then
+    echo "  (not found: $pattern)"
+    return 3
+  fi
+
+  echo "### $label"
+  grep -E "$pattern" "$SCHEMA" -A "$max_lines" | \
+    awk '/^\}$/{print; exit} {print}' | \
+    head -n "$max_lines" || true
+  echo ""
+}
+
+# ── Main loop ────────────────────────────────────────────────────────────────
+
+for ENTITY in "$@"; do
+  # Validate entity name: must be a valid PascalCase identifier (letters, digits, underscores)
+  if [[ ! "$ENTITY" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    echo "ERROR: Invalid entity name: '$ENTITY'"
+    echo "  Entity names must start with a letter or underscore, followed by letters, digits, or underscores."
+    echo "  Examples: Account, My_Custom_Object__c"
+    continue
+  fi
+
+  echo ""
+  echo "======================================================================"
+  echo "  SCHEMA LOOKUP: $ENTITY"
+  echo "======================================================================"
+  echo ""
+
+  found=0
+
+  # Helper: call extract_block, track matches, surface errors
+  try_extract() {
+    local rc=0
+    extract_block "$@" || rc=$?
+    if [ "$rc" -eq 0 ]; then
+      found=$((found + 1))
+    elif [ "$rc" -eq 1 ]; then
+      echo "  Aborting lookup for '$ENTITY' due to grep error" >&2
+    fi
+    # rc=3 is not-found — continue silently (already printed by extract_block)
+  }
+
+  # 1. Type definition — all fields and relationships
+  try_extract \
+    "Type definition — fields and relationships" \
+    "^type ${ENTITY} implements Record" \
+    200
+
+  # 2. Filter input — used in `where:` arguments
+  try_extract \
+    "Filter options — use in where: { ... }" \
+    "^input ${ENTITY}_Filter" \
+    100
+
+  # 3. OrderBy input — used in `orderBy:` arguments
+  try_extract \
+    "Sort options — use in orderBy: { ... }" \
+    "^input ${ENTITY}_OrderBy" \
+    60
+
+  # 4. Create mutation wrapper
+  try_extract \
+    "Create mutation wrapper — ${ENTITY}CreateInput" \
+    "^input ${ENTITY}CreateInput" \
+    10
+
+  # 5. Create mutation fields
+  try_extract \
+    "Create mutation fields — ${ENTITY}CreateRepresentation" \
+    "^input ${ENTITY}CreateRepresentation" \
+    100
+
+  # 6. Update mutation wrapper
+  try_extract \
+    "Update mutation wrapper — ${ENTITY}UpdateInput" \
+    "^input ${ENTITY}UpdateInput" \
+    10
+
+  # 7. Update mutation fields
+  try_extract \
+    "Update mutation fields — ${ENTITY}UpdateRepresentation" \
+    "^input ${ENTITY}UpdateRepresentation" \
+    100
+
+  if [ "$found" -eq 0 ]; then
+    echo "WARNING: No schema entries found for '$ENTITY'."
+    echo "  - Names are PascalCase (e.g., 'Account' not 'account')"
+    echo "  - Custom objects may need deployment first"
+  fi
+
+  echo ""
+done

package/lib/templates/project/{reactb2x → reactexternalapp}/scripts/setup-cli.mjs

@@ -14,7 +14,7 @@
  *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
  *   2. webapp    — (all web apps) npm install && npm run build so dist exists for deploy (skip with --skip-webapp-build)
  *   3. deploy    — sf project deploy start --target-org <alias> (requires dist for entity deployment)
- *   4. permset   — sf org assign permset (skip with --skip-permset; name via --permset-name)
+ *   4. permset   — sf org assign permset for each *.permissionset-meta.xml (skip with --skip-permset; override via --permset-name)
  *   5. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
  *   6. graphql   — (in webapp) npm run graphql:schema then npm run graphql:codegen
  *   7. dev       — (in webapp) npm run dev — launch dev server (skip with --skip-dev)
@@ -52,7 +52,8 @@ function parseArgs() {
   const args = process.argv.slice(2);
   let targetOrg = null;
   let webappName = null;
-  let permsetName = 'Property_Management_Access';
+  /** If non-empty, only these names are assigned; otherwise all discovered from the project. */
+  const permsetNamesExplicit = [];
   let yes = false;
   const flags = {
     skipLogin: false,
@@ -69,7 +70,7 @@ function parseArgs() {
     } else if (args[i] === '--webapp-name' && args[i + 1]) {
       webappName = args[++i];
     } else if (args[i] === '--permset-name' && args[i + 1]) {
-      permsetName = args[++i];
+      permsetNamesExplicit.push(args[++i]);
     } else if (args[i] === '--skip-login') flags.skipLogin = true;
     else if (args[i] === '--skip-deploy') flags.skipDeploy = true;
     else if (args[i] === '--skip-permset') flags.skipPermset = true;
@@ -90,7 +91,7 @@ Required:
 
 Options:
   --webapp-name <name>   Web app folder name under webapplications/ (default: auto-detect)
-  --permset-name <name>  Permission set to assign (default: Property_Management_Access)
+  --permset-name <name>  Assign only this permission set (repeatable). Default: all sets under permissionsets/
   --skip-login           Skip login step (login is auto-skipped if org is already connected)
   --skip-deploy          Do not deploy metadata
   --skip-permset         Do not assign permission set
@@ -108,7 +109,7 @@ Options:
     console.error('Error: --target-org <alias> is required.');
     process.exit(1);
   }
-  return { targetOrg, webappName, permsetName, yes, ...flags };
+  return { targetOrg, webappName, permsetNamesExplicit, yes, ...flags };
 }
 
 function discoverAllWebappDirs(webappName) {
@@ -141,6 +142,19 @@ function discoverWebappDir(webappName) {
   return all[0];
 }
 
+/** API names from permissionsets/*.permissionset-meta.xml in the first package directory. */
+function discoverPermissionSetNames() {
+  const dir = resolve(SFDX_SOURCE, 'permissionsets');
+  if (!existsSync(dir)) return [];
+  const names = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const m = entry.name.match(/^(.+)\.permissionset-meta\.xml$/);
+    if (m) names.push(m[1]);
+  }
+  return names.sort();
+}
+
 function isOrgConnected(targetOrg) {
   const result = spawnSync('sf', ['org', 'display', '--target-org', targetOrg, '--json'], {
     cwd: ROOT,
@@ -281,7 +295,7 @@ async function main() {
   const {
     targetOrg,
     webappName,
-    permsetName,
+    permsetNamesExplicit,
     yes,
     skipLogin: argSkipLogin,
     skipDeploy: argSkipDeploy,
@@ -292,13 +306,22 @@ async function main() {
     skipDev: argSkipDev,
   } = parseArgs();
 
+  const permsetNames =
+    permsetNamesExplicit.length > 0 ? permsetNamesExplicit : discoverPermissionSetNames();
+  const permsetStepLabel =
+    permsetNames.length === 0
+      ? 'Permset — (none under permissionsets/)'
+      : permsetNames.length <= 3
+        ? `Permset — assign ${permsetNames.join(', ')}`
+        : `Permset — assign ${permsetNames.length} permission sets`;
+
   const hasDataPlan = existsSync(DATA_PLAN) && existsSync(DATA_DIR);
 
   const stepDefs = [
     { key: 'login', label: 'Login — org authentication', enabled: !argSkipLogin, available: true },
     { key: 'webappBuild', label: 'Webapp Build — npm install + build (pre-deploy)', enabled: !argSkipWebappBuild, available: true },
     { key: 'deploy', label: 'Deploy — sf project deploy start', enabled: !argSkipDeploy, available: true },
-    { key: 'permset', label: `Permset — assign ${permsetName}`, enabled: !argSkipPermset, available: true },
+    { key: 'permset', label: permsetStepLabel, enabled: !argSkipPermset, available: true },
     { key: 'data', label: 'Data — delete + import records via Apex', enabled: !argSkipData && hasDataPlan, available: hasDataPlan },
     { key: 'graphql', label: 'GraphQL — schema introspect + codegen', enabled: !argSkipGraphql, available: true },
     { key: 'dev', label: 'Dev — launch dev server', enabled: !argSkipDev, available: true },
@@ -359,31 +382,38 @@ async function main() {
     });
   }
 
-  if (!skipPermset && permsetName) {
-    console.log('\n--- Assign permission set ---');
-    const permsetResult = spawnSync(
-      'sf',
-      ['org', 'assign', 'permset', '--name', permsetName, '--target-org', targetOrg],
-      {
-        cwd: ROOT,
-        stdio: 'pipe',
-        shell: true,
-      }
-    );
-    if (permsetResult.status === 0) {
-      console.log('Permission set assigned.');
+  if (!skipPermset) {
+    if (permsetNames.length === 0) {
+      console.log('\n--- Assign permission sets ---');
+      console.log('No permission sets found under permissionsets/ and none passed via --permset-name; skipping.');
     } else {
-      const out =
-        (permsetResult.stderr?.toString() || '') + (permsetResult.stdout?.toString() || '');
-      if (out.includes('Duplicate') && out.includes('PermissionSet')) {
-        console.log('Permission set already assigned; skipping.');
-      } else if (out.includes('not found') && out.includes('target org')) {
-        console.log(`Permission set "${permsetName}" not in org; skipping.`);
-      } else {
-        process.stdout.write(permsetResult.stdout?.toString() || '');
-        process.stderr.write(permsetResult.stderr?.toString() || '');
-        console.error('\nSetup failed at step: Assign permission set');
-        process.exit(permsetResult.status ?? 1);
+      console.log('\n--- Assign permission sets ---');
+      for (const permsetName of permsetNames) {
+        const permsetResult = spawnSync(
+          'sf',
+          ['org', 'assign', 'permset', '--name', permsetName, '--target-org', targetOrg],
+          {
+            cwd: ROOT,
+            stdio: 'pipe',
+            shell: true,
+          }
+        );
+        if (permsetResult.status === 0) {
+          console.log(`Permission set "${permsetName}" assigned.`);
+        } else {
+          const out =
+            (permsetResult.stderr?.toString() || '') + (permsetResult.stdout?.toString() || '');
+          if (out.includes('Duplicate') && out.includes('PermissionSet')) {
+            console.log(`Permission set "${permsetName}" already assigned; skipping.`);
+          } else if (out.includes('not found') && out.includes('target org')) {
+            console.log(`Permission set "${permsetName}" not in org; skipping.`);
+          } else {
+            process.stdout.write(permsetResult.stdout?.toString() || '');
+            process.stderr.write(permsetResult.stderr?.toString() || '');
+            console.error(`\nSetup failed at step: Assign permission set (${permsetName})`);
+            process.exit(permsetResult.status ?? 1);
+          }
+        }
       }
     }
   }

package/lib/templates/project/reactexternalapp/scripts/sf-project-setup.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Run from SFDX project root: install dependencies, build, and launch the dev server
+ * for the web app in force-app/main/default/webapplications/.
+ *
+ * Usage: npm run sf-project-setup
+ * (from the directory that contains force-app/ and sfdx-project.json)
+ */
+
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+function resolveWebapplicationsDir() {
+  const sfdxPath = resolve(ROOT, 'sfdx-project.json');
+  if (!existsSync(sfdxPath)) {
+    console.error('Error: sfdx-project.json not found at project root.');
+    process.exit(1);
+  }
+  const sfdxProject = JSON.parse(readFileSync(sfdxPath, 'utf8'));
+  const pkgDir = sfdxProject?.packageDirectories?.[0]?.path;
+  if (!pkgDir) {
+    console.error('Error: No packageDirectories[].path found in sfdx-project.json.');
+    process.exit(1);
+  }
+  return resolve(ROOT, pkgDir, 'main', 'default', 'webapplications');
+}
+
+function discoverWebappDir() {
+  const webapplicationsDir = resolveWebapplicationsDir();
+  if (!existsSync(webapplicationsDir)) {
+    console.error(`Error: webapplications directory not found: ${webapplicationsDir}`);
+    process.exit(1);
+  }
+  const entries = readdirSync(webapplicationsDir, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith('.'));
+  if (dirs.length === 0) {
+    console.error(`Error: No web app folder found under ${webapplicationsDir}`);
+    process.exit(1);
+  }
+  if (dirs.length > 1) {
+    console.log(`Multiple web apps found; using first: ${dirs[0].name}`);
+  }
+  return resolve(webapplicationsDir, dirs[0].name);
+}
+
+function run(label, cmd, args, opts) {
+  console.log(`\n--- ${label} ---\n`);
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const webappDir = discoverWebappDir();
+console.log('SFDX project root:', ROOT);
+console.log('Web app directory:', webappDir);
+
+run('npm install', 'npm', ['install'], { cwd: webappDir });
+run('npm run build', 'npm', ['run', 'build'], { cwd: webappDir });
+console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
+run('npm run dev', 'npm', ['run', 'dev'], { cwd: webappDir });

package/lib/templates/project/reactinternalapp/.forceignore

@@ -0,0 +1,15 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**
+
+node_modules/
+.DS_Store

package/lib/templates/project/{reactb2x → reactinternalapp}/AGENT.md

@@ -54,14 +54,19 @@ cd <sfdx-source>/webapplications/<appName>
 
 **Before finishing changes:** run `npm run build` and `npm run lint` from the web app directory; both must succeed.
 
-## Agent rules (.a4drules)
+## Agent rules (.a4drules/)
 
-This project includes **.a4drules/** at the project root. Follow them when generating or editing code.
+Markdown rules at the project root under **.a4drules/** define platform constraints:
+
+- **`.a4drules/webapp-ui.md`** — Salesforce Web Application UI (scaffold with `sf webapp generate`, no LWC/Aura for new UI).
+- **`.a4drules/webapp-data.md`** — Salesforce data access (Data SDK only, supported APIs, GraphQL workflow, `scripts/graphql-search.sh` for schema lookup).
 
 When rules refer to "web app directory" or `<sfdx-source>/webapplications/<appName>/`, resolve `<sfdx-source>` from `sfdx-project.json` and use the **actual app folder name** for this project.
 
 ## Deploying
 
+**Deployment order:** Metadata (objects, permission sets) must be deployed before GraphQL schema fetch. After any metadata deployment, re-run `npm run graphql:schema` and `npm run graphql:codegen` from the webapp dir. **One-command setup:** `node scripts/setup-cli.mjs --target-org <alias>` runs deploy → permset → schema → codegen in the correct order.
+
 From **this project root** (resolve the actual SFDX source path from `sfdx-project.json`):
 
 ```bash
@@ -79,3 +84,4 @@ sf project deploy start --source-dir <packageDir> --target-org <alias>
 
 - **UI**: shadcn/ui + Tailwind. Import from `@/components/ui/...`.
 - **Entry**: Keep `App.tsx` and routes in `src/`; add features as new routes or sections, don't replace the app shell but you may modify it to match the requested design.
+- **Data (Salesforce)**: Follow `.a4drules/webapp-data.md` for all Salesforce data access. Use the Data SDK (`createDataSDK()` + `sdk.graphql` or `sdk.fetch`) — never use `fetch` or `axios` directly. GraphQL is preferred; use `sdk.fetch` when GraphQL is not sufficient.