@salesforce/templates 66.11.1 → 66.12.0

package/lib/templates/project/angularextapp/scripts/gitignore-templates.json

@@ -0,0 +1,4 @@
+{
+  "sfdx": "# This file is used for Git repositories to specify intentionally untracked files that Git should ignore. \n# If you are not using git, you can delete this file. For more information see: https://git-scm.com/docs/gitignore\n# For useful gitignore templates see: https://github.com/github/gitignore\n\n# Salesforce cache\n.sf/\n.sfdx/\n.localdevserver/\ndeploy-options.json\n\n# LWC VSCode autocomplete\n**/lwc/jsconfig.json\n\n# LWC Jest coverage reports\ncoverage/\n\n# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n\n# Dependency directories\nnode_modules/\n\n# Eslint cache\n.eslintcache\n\n# MacOS system files\n.DS_Store\n\n# Windows system files\nThumbs.db\nehthumbs.db\n[Dd]esktop.ini\n$RECYCLE.BIN/\n\n# Local environment variables\n.env\n\n# Python Salesforce Functions\n**/__pycache__/\n**/.venv/\n**/venv/\n",
+  "webapp": "# See https://docs.github.com/get-started/getting-started-with-git/ignoring-files for more about ignoring files.\n\n# Compiled output\n/dist\n/tmp\n/out-tsc\n/bazel-out\n\n# Node\n/node_modules\nnpm-debug.log\nyarn-error.log\npackage-lock.json\n\n# Playwright\n/test-results/\n/playwright-report/\n/blob-report/\n/playwright/.cache/\n\n# IDEs and editors\n.idea/\n.project\n.classpath\n.c9/\n*.launch\n.settings/\n*.sublime-workspace\n\n# Visual Studio Code\n.vscode/*\n!.vscode/settings.json\n!.vscode/tasks.json\n!.vscode/launch.json\n!.vscode/extensions.json\n!.vscode/mcp.json\n.history/*\n\n# Miscellaneous\n/.angular/cache\n.sass-cache/\n/connect.lock\n/coverage\n/libpeerconnection.log\ntestem.log\n/typings\n__screenshots__/\n\n# System files\n.DS_Store\nThumbs.db\n"
+}

package/lib/templates/project/angularextapp/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 ui-bundle dir:"
+  echo "    cd force-app/main/default/uiBundles/<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 ui-bundle dir:"
+  echo "    cd force-app/main/default/uiBundles/<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/angularextapp/scripts/org-setup-config-schema.mjs

@@ -0,0 +1,103 @@
+/**
+ * Shared schema + validator for org-setup.config.json (W-23043729).
+ *
+ * Authored ONCE, used at TWO moments:
+ *   (a) build / CI time — `scripts/validate-org-setup-config.mjs` validates every
+ *       org-setup.config.json this repo ships, failing the build on any violation.
+ *   (b) setup runtime — `org-setup.mjs` calls `validateConfig` once in main(),
+ *       before any step runs, to catch the developer's local post-scaffold edits.
+ *
+ * `validateConfig` is pure: it parses + validates and RETURNS a result. Each call
+ * site owns its own print/exit, so the build gate can report every bad file and
+ * the runtime can exit immediately — and the validator stays unit-testable.
+ *
+ * The zod schema uses `.strict()` at every level so unknown keys (e.g. the
+ * `permsetAssignment` singular typo) are rejected rather than silently ignored.
+ */
+
+import { z } from 'zod';
+
+/** Closed set of assignee values — no arbitrary usernames. */
+const Assignee = z.enum(['currentUser', 'guestUser', 'skip']);
+
+// No siteName: for guestUser the site is derived from the single
+// networks/<siteName>.network-meta.xml the app ships (see spec §5.2).
+const Assignment = z
+  .object({
+    assignee: Assignee,
+  })
+  .strict();
+
+export const ConfigSchema = z
+  .object({
+    permsetAssignments: z
+      .object({
+        // guestUser is valid here — siteName is derived, not per-assignment.
+        defaultAssignee: Assignee.default('skip'),
+        assignments: z.record(z.string(), Assignment).default({}),
+      })
+      .strict()
+      .optional(),
+    role: z
+      .object({
+        assignee: z.literal('currentUser'), // only value the role code honors
+        roleName: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+    selfRegistration: z
+      .object({
+        // No siteName: the site is derived from the single
+        // networks/<siteName>.network-meta.xml the app ships (see spec §5.2),
+        // exactly like the guestUser permset path.
+        //
+        // selfRegProfile also drives the M1 license pre-check (W-23043735):
+        // setup derives the required UserLicense from this profile
+        // (Profile.UserLicense, matched on the stable LicenseDefinitionKey) and
+        // warns + skips self-registration when the org lacks it or has no seats.
+        // No separate license field is declared — the requirement can't drift
+        // from the profile the flow actually assigns.
+        selfRegProfile: z.string().min(1),
+        accountName: z.string().min(1),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+/**
+ * Render a single zod issue as a "path: message" line. Empty path (a root-level
+ * problem) renders as "<root>: message".
+ */
+function formatIssue(issue) {
+  const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+  return `${path}: ${issue.message}`;
+}
+
+/**
+ * Parse + validate a raw org-setup.config.json string.
+ *
+ * @param {string} rawText  raw file contents (not yet JSON-parsed)
+ * @param {string} [configPath]  path used only for error messages
+ * @returns {{ ok: true, data: object } | { ok: false, errors: string[] }}
+ *   On success, `data` is the parsed + defaulted config. On failure, `errors`
+ *   is a non-empty list of human-readable messages (JSON parse error or zod
+ *   issues). The caller decides whether to print/exit.
+ */
+export function validateConfig(rawText, configPath) {
+  const where = configPath ? ` (${configPath})` : '';
+
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (err) {
+    return { ok: false, errors: [`malformed JSON${where}: ${err.message}`] };
+  }
+
+  const result = ConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    return { ok: false, errors: result.error.issues.map(formatIssue) };
+  }
+
+  return { ok: true, data: result.data };
+}

package/lib/templates/project/angularextapp/scripts/org-setup-dev.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Dev preview: refresh the GraphQL schema/types against a target org, then launch
+ * the Vite dev server (spec §5.5, M4). This is the step that used to be the final
+ * `dev` stage of org-setup.mjs — extracted here so `npm run setup` terminates
+ * cleanly after graphql, and the long-lived dev server is an explicit, separate
+ * `npm run dev:preview`.
+ *
+ * Unlike setup, this does NOT log in or deploy — it assumes the org is already
+ * set up. It shares org/bundle resolution and the process runner with org-setup
+ * via org-setup-utils.mjs.
+ *
+ * Usage:
+ *   npm run dev:preview                                 # prompt to pick an org + bundle
+ *   npm run dev:preview -- --target-org myorg
+ *   npm run dev:preview -- --target-org myorg --ui-bundle-name my-app
+ *
+ * Flow (in order):
+ *   1. resolve target org (explicit --target-org, else prompt / default org)
+ *   2. resolve UI bundle (explicit --ui-bundle-name, else picker / warning)
+ *   3. npm install            (in the UI bundle)
+ *   4. npm run graphql:schema (SF_TARGET_ORG=<org>)  — introspect the live schema
+ *   5. npm run graphql:codegen                       — regenerate typed operations
+ *   6. npm run dev            (blocking, Ctrl+C to stop)
+ */
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { run, resolveSfdxSource, discoverUIBundleDir, resolveTargetOrg } from './org-setup-utils.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let targetOrg = null;
+  let uiBundleName = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--target-org' && args[i + 1]) {
+      targetOrg = args[++i];
+    } else if (args[i] === '--ui-bundle-name' && args[i + 1]) {
+      uiBundleName = args[++i];
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      console.log(`
+Dev preview — refresh GraphQL types then launch the Vite dev server
+
+Usage:
+  npm run dev:preview -- [--target-org <alias>] [--ui-bundle-name <name>]
+
+Options:
+  --target-org <alias>    Target Salesforce org alias. If omitted, you are prompted
+                          to pick from authenticated orgs (or the default org is used).
+  --ui-bundle-name <name> UI bundle folder under uiBundles/ (default: auto-detect / prompt)
+  -h, --help              Show this help
+`);
+      process.exit(0);
+    }
+  }
+  return { targetOrg, uiBundleName };
+}
+
+async function main() {
+  const parsed = parseArgs();
+
+  const targetOrg = await resolveTargetOrg(parsed);
+  const uiBundlesDir = resolve(resolveSfdxSource(ROOT), 'uiBundles');
+  const uiBundleDir = await discoverUIBundleDir(uiBundlesDir, parsed.uiBundleName);
+
+  console.log('Dev preview — target org:', targetOrg, '| UI bundle:', uiBundleDir);
+
+  run('UI Bundle npm install', 'npm', ['install'], { cwd: uiBundleDir });
+  run('GraphQL schema (introspect)', 'npm', ['run', 'graphql:schema'], {
+    cwd: uiBundleDir,
+    env: { ...process.env, SF_TARGET_ORG: targetOrg },
+  });
+  run('GraphQL codegen', 'npm', ['run', 'graphql:codegen'], { cwd: uiBundleDir });
+
+  console.log('\n--- Launching dev server (Ctrl+C to stop) ---\n');
+  const devResult = run('Dev server', 'npm', ['run', 'dev'], { cwd: uiBundleDir, optional: true });
+  process.exit(devResult.status ?? 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});