@salesforce/templates 66.5.6 → 66.6.0

package/lib/templates/project/reactb2e/_r_/skills/deploying-to-salesforce/SKILL.md

@@ -1,226 +0,0 @@
----
-name: deploying-to-salesforce
-description: Enforces the correct order for deploying metadata, assigning permission sets, and fetching GraphQL schema. Use for ANY deployment to a Salesforce org — webapps, LWC, Aura, Apex, metadata, schema fetch, or org sync. Codifies setup-cli.mjs.
----
-
-# Deploying to Salesforce
-
-Guidance for AI agents deploying metadata to a Salesforce org or syncing with the org. **The order of operations is critical.** This skill codifies the exact sequence from `scripts/setup-cli.mjs` and documents **every Salesforce interaction**.
-
-## When to Use
-
-Invoke this skill whenever the task involves:
-
-- Deploying metadata (objects, permission sets, layouts, Apex, web applications)
-- Generating deploy commands or setup instructions
-- Fetching the GraphQL schema (`npm run graphql:schema`)
-- Running GraphQL codegen (`npm run graphql:codegen`)
-- Full org setup (login, deploy, permset, data, schema, build)
-- Any manual step that touches the Salesforce org
-
-## Canonical Sequence (from setup-cli.mjs)
-
-Execute steps in this **exact order**. Steps marked **(SF)** perform a Salesforce API or CLI interaction.
-
-### Step 1: Login — org authentication
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Check if org is connected | **(SF)** | `sf org display --target-org <alias> --json` |
-| If not connected: authenticate | **(SF)** | `sf org login web --alias <alias>` |
-
-- **Run when:** Org is not connected. **Omit when:** Org is already authenticated (check via `sf org display`).
-- All subsequent steps require an authenticated org.
-
-### Step 2: Webapp build — pre-deploy (required for entity deployment)
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Install dependencies | No | `npm install` (in each webapp dir) |
-| Build web app | No | `npm run build` (in each webapp dir) |
-
-- Produces `dist/` so `sf project deploy start` can deploy web application entities. Run **before** deploy when deploying web apps.
-- **Run when:** Deploying web apps AND (`dist/` does not exist OR webapp source has changed since last build). **Omit when:** Not deploying, or `dist/` is current and no source changes.
-
-### Step 3: Deploy metadata
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Deploy metadata | **(SF)** | See below |
-
-**Check for a manifest (package.xml) first.** Only use it if present:
-
-- **If `manifest/package.xml` (or `package.xml`) exists:** Deploy using the manifest:
-  ```bash
-  sf project deploy start --manifest manifest/package.xml --target-org <alias>
-  ```
-- **If no manifest exists:** Deploy all metadata from the project (packageDirectories in sfdx-project.json):
-  ```bash
-  sf project deploy start --target-org <alias>
-  ```
-
-Do not assume a manifest exists. Check the project root and common locations (e.g., `manifest/`, `config/`) before choosing the deploy command.
-
-- Deploys objects, layouts, permission sets, Apex classes, web applications, and all other metadata.
-- **Must complete successfully before schema fetch** — the schema reflects org state; custom objects/fields appear only after deployment.
-- **Run when:** Metadata has changed since last deploy, or never deployed. **Omit when:** No metadata changes and deploy has already run successfully.
-
-### Step 4: Post-deployment configuration — assign permissions and configure
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Assign permission set or group | **(SF)** | `sf org assign permset --name <name> --target-org <alias>` (works for both permsets and permset groups) |
-| Assign profile to user | **(SF)** | `sf data update record` or at user creation |
-| Other post-deploy config | **(SF)** | Varies (e.g., named credentials, connected apps, custom settings) |
-
-**Example commands:**
-
-```bash
-# Permission set (assigns to default user of target org)
-sf org assign permset --name Property_Management_Access --target-org myorg
-
-# Permission set group (same command; pass the group name)
-sf org assign permset --name My_Permset_Group --target-org myorg
-
-# Assign to a specific user
-sf org assign permset --name Property_Management_Access --target-org myorg --on-behalf-of user@example.com
-
-# Profile — update existing user's profile (requires ProfileId and User Id)
-sf data update record --sobject User --record-id <userId> --values "ProfileId=<profileId>" --target-org myorg
-
-# Profile — get ProfileId first
-sf data query --query "SELECT Id, Name FROM Profile WHERE Name='Standard User'" --target-org myorg
-```
-
-- **Deploying does not mean assigning.** Even after permission sets, permission set groups, and profiles are deployed to the org, they must be explicitly assigned or configured for users. Deployment makes them available; assignment/configuration grants access.
-- **Permission sets** — Assign to users so they have access to custom objects and fields. Required for GraphQL introspection to return the correct schema.
-- **Permission set groups** — Assign to users when using grouped permission sets.
-- **Profiles** — Ensure users have the correct profile; profile assignment may be done at user creation or via Setup.
-- **Other post-deploy configuration** — Named credentials, connected apps, custom settings, flow activation, and any metadata that requires manual configuration after deploy.
-- All of the above must exist in the org (deployed in Step 3).
-- **Run when:** Any permission set, permission set group, profile, or other post-deploy config was deployed or changed and not yet assigned/configured. **Omit when:** All required assignments and configuration are already in place.
-
-**Proactive behavior:** After a successful deploy, discover permission sets in the project (e.g., `force-app/main/default/permissionsets/*.permissionset-meta.xml`) and assign each one. Extract the API name from the filename (e.g., `Property_Management_Access.permissionset-meta.xml` → `Property_Management_Access`). If the user has not explicitly requested a full setup, you may ask: "Do you want me to assign the permission sets to your org?" — but do not skip this step silently; either run it or ask.
-
-### Step 5: Data — prepare and import (optional)
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Prepare unique fields | No | `node scripts/prepare-import-unique-fields.js --data-dir <dataDir>` |
-| Clean existing records | **(SF)** | `sf apex run --target-org <alias> --file <apex>` (per sobject, reverse plan order) |
-| Import records | **(SF)** | `sf apex run --target-org <alias> --file <apex>` (per batch) |
-
-- Only runs if `data/data-plan.json` and `data/` exist.
-- Delete runs in reverse plan order (children before parents).
-- Import uses Anonymous Apex with `Database.DMLOptions.duplicateRuleHeader.allowSave = true`.
-- **Run when:** Data plan exists AND (never imported OR data files or plan changed). **Omit when:** No data plan, or data already imported and unchanged.
-
-**Proactive behavior:** If `data/data-plan.json` and `data/` exist, you MUST ask the user: "Do you want me to import the sample data now? This will prepare unique fields, optionally clean existing records, and import data. Reply yes to proceed." Do not skip this step silently; either run it (after confirmation) or ask. Never import or clean without explicit user confirmation.
-
-### Step 6: GraphQL schema and codegen
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Install webapp deps | No | `npm install` (in webapp dir) |
-| Set default org | **(SF)** | `sf config set target-org <alias> --global` |
-| Fetch schema (introspection) | **(SF)** | `npm run graphql:schema` (from webapp dir) |
-| Generate types | No | `npm run graphql:codegen` (from webapp dir) |
-
-- `graphql:schema` performs GraphQL introspection against the org — a **Salesforce API call**.
-- Schema is written to `schema.graphql` at the SFDX project root.
-- Codegen reads the schema file locally; no Salesforce interaction.
-- **Run when:** Schema does not exist, OR metadata was deployed/changed since last schema fetch, OR permissions or post-deploy config was assigned since last schema fetch. **Omit when:** Schema exists and is current relative to org state.
-
-### Step 7: Webapp build (if not done in Step 2)
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Build web app | No | `npm run build` (in webapp dir) |
-
-- **Run when:** Build is needed (e.g., for dev server or deploy) AND (`dist/` does not exist OR webapp source has changed since last build). **Omit when:** `dist/` is current and no build needed.
-
-### Step 8: Dev server (optional)
-
-| Action | Salesforce interaction? | Command |
-|--------|-------------------------|---------|
-| Launch dev server | No | `npm run dev` (in webapp dir) |
-
-- **Run when:** User requests to launch the dev server. **Omit when:** Not requested.
-
-## Summary: All Salesforce Interactions (in order)
-
-1. `sf org display` — check org connection
-2. `sf org login web` — authenticate (if needed)
-3. `sf project deploy start` — deploy metadata
-4. `sf org assign permset` (permsets and permset groups) / profile assignment / other post-deploy config — assign permissions and configure
-5. `sf apex run` — delete existing data (if data plan)
-6. `sf apex run` — import data (if data plan)
-7. `sf config set target-org` — set default org for schema
-8. `npm run graphql:schema` — GraphQL introspection (Salesforce API)
-
-## Post-Deploy Checklist (MUST NOT SKIP)
-
-After **every successful metadata deploy**, the agent MUST address these before considering the task complete:
-
-1. **Permission sets** — Discover `force-app/main/default/permissionsets/*.permissionset-meta.xml`, extract API names, and assign each via `sf org assign permset --name <name> --target-org <alias>`. If unsure, ask: "Do you want me to assign the permission sets (e.g., Property_Management_Access, Tenant_Maintenance_Access) to your org?"
-2. **Data import** — If `data/data-plan.json` exists, ask: "Do you want me to import the sample data now? Reply yes to proceed." Do not import without confirmation.
-3. **Schema refetch** — Run `npm run graphql:schema` and `npm run graphql:codegen` from the webapp dir (required after deploy).
-
-Do not silently skip permission set assignment or data import. Either run them or ask the user.
-
-## Agent Decision Criteria
-
-Evaluate each step before running it. Ask:
-
-- **Has this step ever run before?** If not, it is likely needed.
-- **Have changes been made that require this step?** (e.g., metadata edits → deploy; deploy → schema refetch)
-- **Is the current state sufficient?** (e.g., org connected, schema exists and is current, permissions and post-deploy config assigned)
-
-Do not rely on CLI flags. Decide based on project state and what has changed.
-
-## Evaluation: When Each Step Touches Salesforce
-
-| Step | Salesforce interaction | Run when |
-|------|------------------------|----------|
-| 1. Login | Yes | Org not connected |
-| 2. Webapp build | No | Deploying web apps AND dist missing or source changed |
-| 3. Deploy | Yes | Metadata changed or never deployed |
-| 4. Post-deploy config | Yes | Permission sets, permset groups, profiles, or other config deployed/changed and not assigned |
-| 5. Data | Yes | Data plan exists AND (never imported OR data changed) |
-| 6. GraphQL | Yes (schema only) | Schema missing or metadata/permissions changed since last fetch |
-| 7. Webapp build | No | Build needed AND dist missing or source changed |
-| 8. Dev | No | User requests dev server |
-
-**Critical rule:** Steps 3 (deploy) and 4 (post-deploy config) must complete **before** step 6 (graphql:schema). The schema reflects the org state; running introspection too early yields an incomplete schema.
-
-## Schema Refetch Rule (CRITICAL)
-
-**After any metadata deployment**, you MUST re-run schema fetch and codegen:
-
-- New custom objects
-- New custom fields
-- New or updated permission sets
-- Any change to metadata that affects the GraphQL schema
-
-```bash
-# From webapp dir (force-app/main/default/webapplications/<appName>/)
-npm run graphql:schema
-npm run graphql:codegen
-```
-
-Do **not** assume the existing `schema.graphql` is current after metadata changes.
-
-## One-Command Setup (Reference)
-
-The project includes `scripts/setup-cli.mjs` which runs this sequence in batch. Use it when the user wants a full setup; otherwise, follow this skill and run only the steps that are needed based on current state.
-
-## Prohibited Actions
-
-- **Do not** run `npm run graphql:schema` before metadata is deployed — the schema will not include custom objects/fields
-- **Do not** skip schema refetch after deploying new metadata — types and queries will be out of sync
-- **Do not** assign permissions or configure before deploying — permission sets, permset groups, and profiles must exist in the org first
-- **Do not** run GraphQL introspection before assigning permissions — the user may lack FLS for custom fields
-
-## Related Skills
-
-- **using-salesforce-data** — Full data access workflow (GraphQL queries/mutations, REST APIs, schema exploration, webapp integration)

package/lib/templates/project/reactb2e/_r_/skills/implementing-file-upload/SKILL.md

@@ -1,396 +0,0 @@
----
-name: implementing-file-upload
-description: Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR.
----
-
-# File Upload API (workflow)
-
-When the user wants file upload functionality in a React webapp, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
-
-## CRITICAL: This is an API-only package
-
-The package exports **programmatic APIs**, not React components or hooks. You will:
-
-- Use the `upload()` function to handle file uploads with progress tracking
-- Build your own custom UI (file input, dropzone, progress bars, etc.)
-- Track upload progress through the `onProgress` callback
-
-**Do NOT:**
-
-- Expect pre-built components like `<FileUpload />` — they are not exported
-- Try to import React hooks like `useFileUpload` — they are not exported
-- Look for dropzone components — they are not exported
-
-The source code contains reference components for demonstration, but they are **not available** as imports. Use them as examples to build your own UI.
-
-## 1. Install the package
-
-```bash
-npm install @salesforce/webapp-template-feature-react-file-upload-experimental
-```
-
-Dependencies are automatically installed:
-
-- `@salesforce/webapp-experimental` (API client)
-- `@salesforce/sdk-data` (data SDK)
-
-## 2. Understand the three upload patterns
-
-### Pattern A: Basic upload (no record linking)
-
-Upload files to Salesforce and get back `contentBodyId` for each file. No ContentVersion record is created.
-
-**When to use:**
-
-- User wants to upload files first, then create/link them to a record later
-- Building a multi-step form where the record doesn't exist yet
-- Deferred record linking scenarios
-
-```tsx
-import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-
-const results = await upload({
-  files: [file1, file2],
-  onProgress: (progress) => {
-    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
-  },
-});
-
-// results[0].contentBodyId: "069..." (always available)
-// results[0].contentVersionId: undefined (no record linked)
-```
-
-### Pattern B: Upload with immediate record linking
-
-Upload files and immediately link them to an existing Salesforce record by creating ContentVersion records.
-
-**When to use:**
-
-- Record already exists (Account, Opportunity, Case, etc.)
-- User wants files immediately attached to the record
-- Direct upload-and-attach scenarios
-
-```tsx
-import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-
-const results = await upload({
-  files: [file1, file2],
-  recordId: "001xx000000yyyy", // Existing record ID
-  onProgress: (progress) => {
-    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
-  },
-});
-
-// results[0].contentBodyId: "069..." (always available)
-// results[0].contentVersionId: "068..." (linked to record)
-```
-
-### Pattern C: Deferred record linking (record creation flow)
-
-Upload files without a record, then link them after the record is created.
-
-**When to use:**
-
-- Building a "create record with attachments" form
-- Record doesn't exist until form submission
-- Need to upload files before knowing the final record ID
-
-```tsx
-import {
-  upload,
-  createContentVersion,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-
-// Step 1: Upload files (no recordId)
-const uploadResults = await upload({
-  files: [file1, file2],
-  onProgress: (progress) => console.log(progress),
-});
-
-// Step 2: Create the record
-const newRecordId = await createRecord(formData);
-
-// Step 3: Link uploaded files to the new record
-for (const file of uploadResults) {
-  const contentVersionId = await createContentVersion(
-    new File([""], file.fileName),
-    file.contentBodyId,
-    newRecordId,
-  );
-}
-```
-
-## 3. Build your custom UI
-
-The package provides the backend — you build the frontend. Here's a minimal example:
-
-```tsx
-import {
-  upload,
-  type FileUploadProgress,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-import { useState } from "react";
-
-function CustomFileUpload({ recordId }: { recordId?: string }) {
-  const [progress, setProgress] = useState<Map<string, FileUploadProgress>>(new Map());
-
-  const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
-    const files = Array.from(event.target.files || []);
-
-    await upload({
-      files,
-      recordId,
-      onProgress: (fileProgress) => {
-        setProgress((prev) => new Map(prev).set(fileProgress.fileName, fileProgress));
-      },
-    });
-  };
-
-  return (
-    <div>
-      <input type="file" multiple onChange={handleFileSelect} />
-
-      {Array.from(progress.entries()).map(([fileName, fileProgress]) => (
-        <div key={fileName}>
-          {fileName}: {fileProgress.status} - {fileProgress.progress}%
-          {fileProgress.error && <span>Error: {fileProgress.error}</span>}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## 4. Track upload progress
-
-The `onProgress` callback fires multiple times for each file as it moves through stages:
-
-| Status         | When                                           | Progress Value       |
-| -------------- | ---------------------------------------------- | -------------------- |
-| `"pending"`    | File queued for upload                         | `0`                  |
-| `"uploading"`  | Upload in progress (XHR)                       | `0-100` (percentage) |
-| `"processing"` | Creating ContentVersion (if recordId provided) | `0`                  |
-| `"success"`    | Upload complete                                | `100`                |
-| `"error"`      | Upload failed                                  | `0`                  |
-
-**Always provide visual feedback:**
-
-- Show file name
-- Display current status
-- Render progress bar for "uploading" status
-- Show error message if status is "error"
-
-## 5. Cancel uploads (optional)
-
-Use an `AbortController` to allow users to cancel uploads:
-
-```tsx
-const abortController = new AbortController();
-
-const handleUpload = async (files: File[]) => {
-  try {
-    await upload({
-      files,
-      signal: abortController.signal,
-      onProgress: (progress) => console.log(progress),
-    });
-  } catch (error) {
-    console.error("Upload cancelled or failed:", error);
-  }
-};
-
-const cancelUpload = () => {
-  abortController.abort();
-};
-```
-
-## 6. Link to current user (special case)
-
-If the user wants to upload files to their own profile or personal library:
-
-```tsx
-import {
-  upload,
-  getCurrentUserId,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-
-const userId = await getCurrentUserId();
-await upload({ files, recordId: userId });
-```
-
-## API Reference
-
-### upload(options)
-
-Main upload API that handles complete flow with progress tracking.
-
-```typescript
-interface UploadOptions {
-  files: File[];
-  recordId?: string | null; // If provided, creates ContentVersion
-  onProgress?: (progress: FileUploadProgress) => void;
-  signal?: AbortSignal; // Optional cancellation
-}
-
-interface FileUploadProgress {
-  fileName: string;
-  status: "pending" | "uploading" | "processing" | "success" | "error";
-  progress: number; // 0-100 for uploading, 0 for other states
-  error?: string;
-}
-
-interface FileUploadResult {
-  fileName: string;
-  size: number;
-  contentBodyId: string; // Always available
-  contentVersionId?: string; // Only if recordId was provided
-}
-```
-
-**Returns:** `Promise<FileUploadResult[]>`
-
-### createContentVersion(file, contentBodyId, recordId)
-
-Manually create a ContentVersion record from a previously uploaded file.
-
-```typescript
-async function createContentVersion(
-  file: File,
-  contentBodyId: string,
-  recordId: string,
-): Promise<string | undefined>;
-```
-
-**Parameters:**
-
-- `file` — File object (used for metadata like name)
-- `contentBodyId` — ContentBody ID from previous upload
-- `recordId` — Record ID for FirstPublishLocationId
-
-**Returns:** ContentVersion ID if successful
-
-### getCurrentUserId()
-
-Get the current user's Salesforce ID.
-
-```typescript
-async function getCurrentUserId(): Promise<string>;
-```
-
-**Returns:** Current user ID
-
-## Common UI patterns
-
-### File input with button
-
-```tsx
-<input type="file" multiple accept=".pdf,.doc,.docx,.jpg,.png" onChange={handleFileSelect} />
-```
-
-### Drag-and-drop zone
-
-Build your own dropzone using native events:
-
-```tsx
-function DropZone({ onDrop }: { onDrop: (files: File[]) => void }) {
-  const handleDrop = (e: React.DragEvent) => {
-    e.preventDefault();
-    const files = Array.from(e.dataTransfer.files);
-    onDrop(files);
-  };
-
-  return (
-    <div
-      onDrop={handleDrop}
-      onDragOver={(e) => e.preventDefault()}
-      style={{ border: "2px dashed #ccc", padding: "2rem" }}
-    >
-      Drop files here
-    </div>
-  );
-}
-```
-
-### Progress bar
-
-```tsx
-{
-  progress.status === "uploading" && (
-    <div style={{ width: "100%", background: "#eee" }}>
-      <div
-        style={{
-          width: `${progress.progress}%`,
-          background: "#0176d3",
-          height: "8px",
-        }}
-      />
-    </div>
-  );
-}
-```
-
-## Decision tree for agents
-
-**User asks for file upload functionality:**
-
-1. **Ask about record context:**
-   - "Do you want to link uploaded files to a specific record, or upload them first and link later?"
-
-2. **Based on response:**
-   - **Link to existing record** → Use Pattern B with `recordId`
-   - **Upload first, link later** → Use Pattern A (no recordId), then Pattern C for linking
-   - **Link to current user** → Use Pattern B with `getCurrentUserId()`
-
-3. **Build the UI:**
-   - Create file input or dropzone (not provided by package)
-   - Add progress display for each file (status + progress bar)
-   - Handle errors in the UI
-
-4. **Test the implementation:**
-   - Verify progress callbacks fire correctly
-   - Check that `contentBodyId` is returned
-   - If `recordId` was provided, verify `contentVersionId` is returned
-
-## Reference implementation
-
-The package includes a reference implementation in `src/features/fileupload/` with:
-
-- `FileUpload.tsx` — Complete component with dropzone and dialog
-- `FileUploadDialog.tsx` — Progress tracking dialog
-- `FileUploadDropZone.tsx` — Drag-and-drop zone
-- `useFileUpload.ts` — React hook for state management
-
-**These are NOT exported** but can be viewed as examples. Read the source files to understand patterns for building your own UI.
-
-## Troubleshooting
-
-**Upload fails with CORS error:**
-
-- Ensure the webapp is properly deployed to Salesforce or running on `localhost`
-- Check that the org allows the origin in CORS settings
-
-**No progress updates:**
-
-- Verify `onProgress` callback is provided
-- Check that the callback function updates React state correctly
-
-**ContentVersion not created:**
-
-- Verify `recordId` is provided to `upload()` function
-- Check that the record ID is valid and exists in the org
-- Ensure user has permissions to create ContentVersion records
-
-**Files upload but don't appear in record:**
-
-- Verify `recordId` is correct
-- Check that ContentVersion was created (look for `contentVersionId` in results)
-- Confirm user has access to view files on the record
-
-## DO NOT do these things
-
-- ❌ Build XHR/fetch upload logic from scratch — use the `upload()` API
-- ❌ Try to import `<FileUpload />` component — it's not exported
-- ❌ Try to import `useFileUpload` hook — it's not exported
-- ❌ Use third-party file upload libraries when this feature exists
-- ❌ Skip progress tracking — always provide user feedback
-- ❌ Ignore errors — always handle and display error messages