@salesforce/webapp-template-app-react-template-b2e-experimental 1.92.0 → 1.93.0

package/dist/.a4drules/skills/feature-react-file-upload-file-upload/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: feature-react-file-upload-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

package/dist/.a4drules/webapp-cli-commands.md

@@ -0,0 +1,88 @@
+---
+description: CLI command generation rules — no node -e one-liners; safe quoting and scripts
+paths:
+  - "**/webapplications/**/*"
+---
+
+# A4D Enforcement: CLI Command Generation & No `node -e` One-Liners
+
+When **generating any CLI/shell commands** (for the user or for automation), follow the rules below. Default shell is **Zsh** (macOS); commands must work there without Bash-only syntax.
+
+---
+
+## 1. Never Use Complex `node -e` One-Liners
+
+**Forbidden:** `node -e` (or `node -p`, `node --eval`) for file manipulation, string replacement, reading/writing configs, or multi-line logic.
+
+**Why:** In Zsh, `node -e '...'` **silently breaks** due to:
+- **`!` (history expansion):** Zsh expands `!` in double-quoted strings → `event not found` or wrong output.
+- **Backticks:** `` ` `` is command substitution; the shell runs it before Node sees the string.
+- **Nested quoting:** Escaping differs between Bash and Zsh; multi-line JS in one string is fragile.
+
+**Allowed:** Trivial one-line only if it has **no** backticks, no `!`, no nested quotes, no multi-line, no `fs` usage. Example: `node -e "console.log(1+1)"`. If in doubt, **use a script file**.
+
+---
+
+## 2. How To Generate CLI Commands Correctly
+
+### Run Node scripts by path, not inline code
+
+- **Do:** `node scripts/setup-cli.mjs --target-org myorg`
+- **Do:** `node path/to/script.mjs arg1 arg2`
+- **Do not:** `node -e "require('fs').writeFileSync(...)"` or any non-trivial inline JS.
+
+### For file edits or transforms
+
+1. **Prefer IDE/agent file tools** (StrReplace, Write, etc.) — they avoid the shell.
+2. **Otherwise:** write a **temporary `.js` or `.mjs` file**, run it, then remove it. Use a **heredoc with quoted delimiter** so the shell does not interpret `$`, `` ` ``, or `!`:
+
+```bash
+cat > /tmp/_transform.js << 'SCRIPT'
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+data.name = 'my-app';
+fs.writeFileSync('package.json', JSON.stringify(data, null, 2) + '\n');
+SCRIPT
+node /tmp/_transform.js && rm /tmp/_transform.js
+```
+
+3. **Simple replacements:** `sed -i '' 's/old/new/g' path/to/file` (macOS: `-i ''`).
+4. **JSON:** `jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json`.
+
+### Quoting and shell safety
+
+- Use **single quotes** around the outer shell string when the inner content has `$`, `` ` ``, or `!`.
+- For heredocs that must be literal, use **`<< 'END'`** (quoted delimiter) so the body is not expanded.
+- **Do not** generate commands that rely on Bash-only features (e.g. `[[ ]]` is fine in Zsh; avoid `source` vs `.` if you need POSIX).
+
+### Paths and working directory
+
+- **State where to run from** when it matters, e.g. "From project root" or "From `force-app/main/default/webapplications/<appName>`".
+- Prefer **explicit paths** or `cd <dir> && ...` so the command is copy-paste safe.
+- This project: setup is `node scripts/setup-cli.mjs --target-org <alias>` from **project root**. Web app commands (`npm run dev`, `npm run build`, `npm run lint`) run from the **web app directory** (e.g. `force-app/main/default/webapplications/<appName>` or `**/webapplications/<appName>`).
+
+### npm / npx
+
+- Use **exact package names** (e.g. `npx @salesforce/webapps-features-experimental list`).
+- For app-specific scripts, **cd to the web app directory first**, then run `npm run <script>` or `npm install ...`.
+- Chain steps with `&&`; one logical command per line is clearer than one giant line.
+
+### Summary checklist when generating a command
+
+- [ ] No `node -e` / `node -p` / `node --eval` with complex or multi-line code.
+- [ ] If Node logic is needed, use `node path/to/script.mjs` or a temp script with heredoc `<< 'SCRIPT'`.
+- [ ] No unescaped `!`, `` ` ``, or `$` in double-quoted strings in Zsh.
+- [ ] Working directory and required args (e.g. `--target-org`) are clear.
+- [ ] Prefer file-editing tools over shell one-liners when editing project files.
+
+---
+
+## 3. Violation Handling
+
+- If a generated command used a complex `node -e` one-liner, **revert and redo** using a script file, `sed`/`jq`, or IDE file tools.
+- If the user sees `event not found`, `unexpected token`, or garbled output, **check for**:
+  - `node -e` with special characters,
+  - Double-quoted strings containing `!` or backticks,
+  - Wrong working directory or missing args.
+
+**Cross-reference:** **webapp.md** (MUST FOLLOW #1) summarizes the no–`node -e` rule; this file is the full reference for CLI command generation and alternatives.

package/dist/.a4drules/webapp-react-code-quality.md

@@ -1,7 +1,7 @@
 ---
 description: Code quality and build validation standards
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Code Quality & Build Validation

package/dist/.a4drules/webapp-react-typescript.md

@@ -1,7 +1,7 @@
 ---
 description: Strict TypeScript standards for type-safe React applications
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # TypeScript Standards

package/dist/.a4drules/webapp-react.md

@@ -1,7 +1,7 @@
 ---
 description: React-specific patterns and Salesforce data access for SFDX web apps
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # React Web App (SFDX)

package/dist/.a4drules/webapp-skills-first.md

@@ -1,7 +1,7 @@
 ---
 description: Always search for and read relevant skills before starting any task
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Skills-First Protocol (MUST FOLLOW)

package/dist/.a4drules/webapp.md

@@ -1,7 +1,7 @@
 ---
 description: Core web application rules for SFDX React apps
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Skills-First (MUST FOLLOW)
@@ -81,7 +81,7 @@ Agents consistently miss these. **You must not leave them default.**
 
 # Shell Command Safety (MUST FOLLOW)
 
-**Never use complex `node -e` one-liners** for file edits or multi-line transforms. They break in Zsh due to `!` history expansion and backtick interpolation. Use a temporary `.js` file, `sed`/`awk`, `jq`, or IDE file-editing tools instead. See **webapp-no-node-e.md** for full details and approved alternatives.
+**Never use complex `node -e` one-liners** for file edits or multi-line transforms. They break in Zsh due to `!` history expansion and backtick interpolation. Use a temporary `.js` file, `sed`/`awk`, `jq`, or IDE file-editing tools instead. See **webapp-cli-commands.md** for full details and approved alternatives.
 
 # Development Cycle
 

package/dist/AGENT.md

@@ -1,11 +1,15 @@
 # Agent guide: SFDX project with React web app
 
-This project is a **Salesforce DX (SFDX) project** containing a **React web application**. The structure is generated; the app lives under `force-app/main/default/webapplications/<appName>/`. Use this file when working in this directory.
+This project is a **Salesforce DX (SFDX) project** containing a **React web application**. The SFDX source path is defined in `sfdx-project.json` (`packageDirectories[].path`); the web app lives under `<sfdx-source>/webapplications/<appName>/`. Use this file when working in this directory.
+
+## SFDX Source Path
+
+The source path prefix is **not** always `force-app`. Read `sfdx-project.json` at the project root, take the first `packageDirectories[].path` value, and append `/main/default` to get `<sfdx-source>`. All paths below use this placeholder.
 
 ## Project layout
 
-- **Project root**: this directory — SFDX project root. Contains `sfdx-project.json`, `force-app/`, and (optionally) LWC/Aura.
-- **React web app**: `force-app/main/default/webapplications/<appName>/`  
+- **Project root**: this directory — SFDX project root. Contains `sfdx-project.json`, the SFDX source directory, and (optionally) LWC/Aura.
+- **React web app**: `<sfdx-source>/webapplications/<appName>/`  
   - Replace `<appName>` with the actual app folder name (e.g. `base-react-app`, or the name chosen when the app was generated).
   - Entry: `src/App.tsx`  
   - Routes: `src/routes.tsx`  
@@ -35,7 +39,7 @@ Root **does not** run the React app. The root `npm run build` is a no-op for the
 **Always `cd` into the web app directory for dev/build/lint/test:**
 
 ```bash
-cd force-app/main/default/webapplications/<appName>
+cd <sfdx-source>/webapplications/<appName>
 ```
 
 | Command | Purpose |
@@ -54,24 +58,24 @@ cd force-app/main/default/webapplications/<appName>
 
 This project includes **.a4drules/** at the project root. Follow them when generating or editing code.
 
-When rules refer to “web app directory” or `force-app/main/default/webapplications/<appName>/`, use the **actual app folder name** for this project.
+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
 
-From **this project root**:
+From **this project root** (resolve the actual SFDX source path from `sfdx-project.json`):
 
 ```bash
-# Build the React app first (replace <appName> with the app folder name)
-cd force-app/main/default/webapplications/<appName> && npm i && npm run build && cd -
+# Build the React app first (replace <sfdx-source> and <appName> with actual values)
+cd <sfdx-source>/webapplications/<appName> && npm i && npm run build && cd -
 
-# Deploy web app only
-sf project deploy start --source-dir force-app/main/default/webapplications --target-org <alias>
+# Deploy web app only (replace <sfdx-source> with actual path, e.g. force-app/main/default)
+sf project deploy start --source-dir <sfdx-source>/webapplications --target-org <alias>
 
-# Deploy all metadata
-sf project deploy start --source-dir force-app --target-org <alias>
+# Deploy all metadata (use the top-level package directory, e.g. force-app)
+sf project deploy start --source-dir <packageDir> --target-org <alias>
 ```
 
 ## Conventions (quick reference)
 
 - **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.
+- **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.

package/dist/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.93.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.92.1...v1.93.0) (2026-03-11)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [1.92.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.92.0...v1.92.1) (2026-03-11)
+
+
+### Bug Fixes
+
+* **template:** make setup-cli data import idempotent with Apex-based insert ([#254](https://github.com/salesforce-experience-platform-emu/webapps/issues/254)) ([76ee673](https://github.com/salesforce-experience-platform-emu/webapps/commit/76ee673f1f13c117f33550dfbb2fff6870a038dc))
+
+
+
+
+
 # [1.92.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.91.0...v1.92.0) (2026-03-11)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.92.0",
+  "version": "1.93.0",
   "description": "Base SFDX project template",
   "private": true,
   "files": [

package/dist/scripts/prepare-import-unique-fields.js

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   node scripts/prepare-import-unique-fields.js
- *   node scripts/prepare-import-unique-fields.js --data-dir /path/to/force-app/main/default/data
+ *   node scripts/prepare-import-unique-fields.js --data-dir /path/to/<sfdx-source>/data
  *
  * Expects data dir to contain (optional) JSON files:
  *   Contact.json (Email with unique domain per run, LastName, FirstName, Phone — standard Contact)
@@ -18,8 +18,22 @@
 const fs = require('fs');
 const path = require('path');
 
-// When run from project root: scripts/prepare-import-unique-fields.js → data dir under force-app
-const DEFAULT_DATA_DIR = path.resolve(__dirname, '..', 'force-app/main/default/data');
+function resolveSfdxSource() {
+  const sfdxPath = path.resolve(__dirname, '..', 'sfdx-project.json');
+  if (!fs.existsSync(sfdxPath)) {
+    console.error('Error: sfdx-project.json not found at project root.');
+    process.exit(1);
+  }
+  const sfdxProject = JSON.parse(fs.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 path.resolve(__dirname, '..', pkgDir, 'main', 'default');
+}
+
+const DEFAULT_DATA_DIR = path.resolve(resolveSfdxSource(), 'data');
 
 function parseArgs() {
   const args = process.argv.slice(2);

package/dist/scripts/setup-cli.mjs

@@ -4,37 +4,56 @@
  * Use this script to make setup easier for each app generated from this template.
  *
  * Usage:
- *   node scripts/setup-cli.mjs --target-org <alias>   # run all steps
+ *   node scripts/setup-cli.mjs --target-org <alias>           # interactive step picker (all selected)
+ *   node scripts/setup-cli.mjs --target-org <alias> --yes     # skip picker, run all steps
  *   node scripts/setup-cli.mjs --target-org afv5 --skip-login
  *   node scripts/setup-cli.mjs --target-org afv5 --skip-data --skip-webapp-build
  *   node scripts/setup-cli.mjs --target-org myorg --webapp-name my-app
  *
  * Steps (in order):
  *   1. login     — sf org login web only if org not already connected (skip with --skip-login)
- *   2. deploy    — sf project deploy start --target-org <alias>
- *   3. permset   — sf org assign permset (skip with --skip-permset; name via --permset-name)
- *   4. data      — prepare unique fields + sf data import tree (skipped if no data dir/plan)
- *   5. graphql   — (in webapp) npm run graphql:schema then npm run graphql:codegen
- *   6. webapp    — (in webapp) npm install && npm run build
+ *   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)
+ *   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)
  */
 
 import { spawnSync } from 'node:child_process';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readdirSync, existsSync } from 'node:fs';
+import { readdirSync, existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
-const WEBAPPLICATIONS_DIR = resolve(ROOT, 'force-app/main/default/webapplications');
-const DATA_DIR = resolve(ROOT, 'force-app/main/default/data');
-const DATA_PLAN = resolve(ROOT, 'force-app/main/default/data/data-plan.json');
+
+function resolveSfdxSource() {
+  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');
+}
+
+const SFDX_SOURCE = resolveSfdxSource();
+const WEBAPPLICATIONS_DIR = resolve(SFDX_SOURCE, 'webapplications');
+const DATA_DIR = resolve(SFDX_SOURCE, 'data');
+const DATA_PLAN = resolve(SFDX_SOURCE, 'data/data-plan.json');
 
 function parseArgs() {
   const args = process.argv.slice(2);
   let targetOrg = null;
   let webappName = null;
   let permsetName = 'Property_Management_Access';
+  let yes = false;
   const flags = {
     skipLogin: false,
     skipDeploy: false,
@@ -58,6 +77,7 @@ function parseArgs() {
     else if (args[i] === '--skip-graphql') flags.skipGraphql = true;
     else if (args[i] === '--skip-webapp-build') flags.skipWebappBuild = true;
     else if (args[i] === '--skip-dev') flags.skipDev = true;
+    else if (args[i] === '--yes' || args[i] === '-y') yes = true;
     else if (args[i] === '--help' || args[i] === '-h') {
       console.log(`
 Setup CLI — one-command setup for apps in this project
@@ -78,6 +98,7 @@ Options:
   --skip-graphql         Do not fetch schema or run GraphQL codegen
   --skip-webapp-build    Do not npm install / build the web application
   --skip-dev             Do not launch the dev server at the end
+  -y, --yes              Skip interactive step picker; run all enabled steps immediately
   -h, --help             Show this help
 `);
       process.exit(0);
@@ -87,18 +108,10 @@ Options:
     console.error('Error: --target-org <alias> is required.');
     process.exit(1);
   }
-  return { targetOrg, webappName, permsetName, ...flags };
+  return { targetOrg, webappName, permsetName, yes, ...flags };
 }
 
-function discoverWebappDir(webappName) {
-  if (webappName) {
-    const dir = resolve(WEBAPPLICATIONS_DIR, webappName);
-    if (!existsSync(dir)) {
-      console.error(`Error: Web app directory not found: ${dir}`);
-      process.exit(1);
-    }
-    return dir;
-  }
+function discoverAllWebappDirs(webappName) {
   if (!existsSync(WEBAPPLICATIONS_DIR)) {
     console.error(`Error: webapplications directory not found: ${WEBAPPLICATIONS_DIR}`);
     process.exit(1);
@@ -109,10 +122,23 @@ function discoverWebappDir(webappName) {
     console.error(`Error: No web app folder found under ${WEBAPPLICATIONS_DIR}`);
     process.exit(1);
   }
-  if (dirs.length > 1) {
-    console.log(`Multiple web apps found; using first: ${dirs[0].name}`);
+  if (webappName) {
+    const requested = dirs.find((d) => d.name === webappName);
+    if (!requested) {
+      console.error(`Error: Web app directory not found: ${webappName}`);
+      process.exit(1);
+    }
+    return [resolve(WEBAPPLICATIONS_DIR, requested.name)];
+  }
+  return dirs.map((d) => resolve(WEBAPPLICATIONS_DIR, d.name));
+}
+
+function discoverWebappDir(webappName) {
+  const all = discoverAllWebappDirs(webappName);
+  if (all.length > 1 && !webappName) {
+    console.log(`Multiple web apps found; using first: ${all[0].split(/[/\\]/).pop()}`);
   }
-  return resolve(WEBAPPLICATIONS_DIR, dirs[0].name);
+  return all[0];
 }
 
 function isOrgConnected(targetOrg) {
@@ -124,6 +150,117 @@ function isOrgConnected(targetOrg) {
   return result.status === 0;
 }
 
+function apexLiteral(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number') return String(value);
+  const s = String(value);
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) return `Date.valueOf('${s}')`;
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(s)) {
+    const dt = s.replace('T', ' ').replace(/\.\d+/, '').replace('Z', '');
+    return `DateTime.valueOf('${dt}')`;
+  }
+  return "'" + s.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'";
+}
+
+function buildApexInsert(sobject, records, refIds) {
+  const lines = [
+    'Database.DMLOptions dmlOpts = new Database.DMLOptions();',
+    'dmlOpts.DuplicateRuleHeader.allowSave = true;',
+    `List<${sobject}> recs = new List<${sobject}>();`,
+  ];
+  for (const rec of records) {
+    lines.push(`{ ${sobject} r = new ${sobject}();`);
+    for (const [key, val] of Object.entries(rec)) {
+      if (key === 'attributes') continue;
+      lines.push(`r.put('${key}', ${apexLiteral(val)});`);
+    }
+    lines.push('recs.add(r); }');
+  }
+  lines.push('Database.SaveResult[] results = Database.insert(recs, dmlOpts);');
+  const refArray = refIds.map((r) => `'${r}'`).join(',');
+  lines.push(`String[] refs = new String[]{${refArray}};`);
+  lines.push('for (Integer i = 0; i < results.size(); i++) {');
+  lines.push("  if (results[i].isSuccess()) System.debug('REF:' + refs[i] + ':' + results[i].getId());");
+  lines.push("  else System.debug('ERR:' + refs[i] + ':' + results[i].getErrors()[0].getMessage());");
+  lines.push('}');
+  return lines.join('\n');
+}
+
+/**
+ * Interactive multi-select: arrow keys navigate, space toggles, 'a' toggles all, enter confirms.
+ * Returns a boolean[] matching the input order.  Falls through immediately when stdin is not a TTY.
+ */
+async function promptSteps(steps) {
+  if (!process.stdin.isTTY) return steps.map((s) => s.enabled);
+
+  const selected = steps.map((s) => s.enabled);
+  let cursor = 0;
+  const DIM = '\x1B[2m';
+  const RST = '\x1B[0m';
+  const CYAN = '\x1B[36m';
+  const GREEN = '\x1B[32m';
+
+  function render() {
+    return steps.map((s, i) => {
+      const ptr = i === cursor ? `${CYAN}❯${RST}` : ' ';
+      if (!s.available) return `${ptr} ${DIM}○ ${s.label} (n/a)${RST}`;
+      const chk = selected[i] ? `${GREEN}●${RST}` : '○';
+      return `${ptr} ${chk} ${s.label}`;
+    });
+  }
+
+  return new Promise((resolve) => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write('\x1B[?25l');
+    console.log('\nSelect steps (↑↓ move, space toggle, a all, enter confirm):\n');
+    process.stdout.write(render().join('\n') + '\n');
+
+    function redraw() {
+      process.stdout.write(`\x1B[${steps.length}A`);
+      for (const line of render()) process.stdout.write(`\x1B[2K${line}\n`);
+    }
+
+    process.stdin.on('data', (key) => {
+      if (key === '\x03') {
+        process.stdout.write('\x1B[?25h\n');
+        process.exit(0);
+      }
+      if (key === '\r' || key === '\n') {
+        process.stdout.write('\x1B[?25h');
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeAllListeners('data');
+        console.log();
+        resolve(selected);
+        return;
+      }
+      if (key === ' ') {
+        if (steps[cursor].available) selected[cursor] = !selected[cursor];
+        redraw();
+        return;
+      }
+      if (key === 'a') {
+        const allOn = steps.every((s, i) => !s.available || selected[i]);
+        for (let i = 0; i < steps.length; i++) {
+          if (steps[i].available) selected[i] = !allOn;
+        }
+        redraw();
+        return;
+      }
+      if (key === '\x1B[A' || key === 'k') {
+        cursor = Math.max(0, cursor - 1);
+        redraw();
+      } else if (key === '\x1B[B' || key === 'j') {
+        cursor = Math.min(steps.length - 1, cursor + 1);
+        redraw();
+      }
+    });
+  });
+}
+
 function run(name, cmd, args, opts = {}) {
   const { cwd = ROOT, optional = false } = opts;
   console.log('\n---', name, '---');
@@ -140,25 +277,52 @@ function run(name, cmd, args, opts = {}) {
   return result;
 }
 
-function main() {
+async function main() {
   const {
     targetOrg,
     webappName,
     permsetName,
-    skipLogin,
-    skipDeploy,
-    skipPermset,
-    skipData,
-    skipGraphql,
-    skipWebappBuild,
-    skipDev,
+    yes,
+    skipLogin: argSkipLogin,
+    skipDeploy: argSkipDeploy,
+    skipPermset: argSkipPermset,
+    skipData: argSkipData,
+    skipGraphql: argSkipGraphql,
+    skipWebappBuild: argSkipWebappBuild,
+    skipDev: argSkipDev,
   } = parseArgs();
 
-  const webappDir = discoverWebappDir(webappName);
   const hasDataPlan = existsSync(DATA_PLAN) && existsSync(DATA_DIR);
-  const doData = !skipData && hasDataPlan;
 
-  console.log('Setup — target org:', targetOrg, '| web app:', webappDir);
+  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: '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 },
+  ];
+
+  const selections = yes ? stepDefs.map((s) => s.enabled) : await promptSteps(stepDefs);
+  const on = {};
+  stepDefs.forEach((s, i) => {
+    on[s.key] = selections[i];
+  });
+
+  const skipLogin = !on.login;
+  const skipWebappBuild = !on.webappBuild;
+  const skipDeploy = !on.deploy;
+  const skipPermset = !on.permset;
+  const skipData = !on.data;
+  const skipGraphql = !on.graphql;
+  const skipDev = !on.dev;
+
+  const needsWebapp = !skipWebappBuild || !skipGraphql || !skipDev;
+  const webappDir = needsWebapp ? discoverWebappDir(webappName) : null;
+  const doData = !skipData;
+
+  console.log('Setup — target org:', targetOrg, '| web app:', webappDir ?? '(none)');
   console.log(
     'Steps: login=%s deploy=%s permset=%s data=%s graphql=%s webapp=%s dev=%s',
     !skipLogin,
@@ -169,11 +333,6 @@ function main() {
     !skipWebappBuild,
     !skipDev
   );
-  if (skipData && hasDataPlan) {
-    console.log('(Data dir present; use without --skip-data to run data import.)');
-  } else if (!hasDataPlan && !skipData) {
-    console.log('(No data plan found; skipping data step.)');
-  }
 
   if (!skipLogin) {
     if (isOrgConnected(targetOrg)) {
@@ -184,6 +343,16 @@ function main() {
     }
   }
 
+  // Build all web apps before deploy so dist exists for entity deployment
+  if (!skipDeploy && !skipWebappBuild) {
+    const allWebappDirs = discoverAllWebappDirs(webappName);
+    for (const dir of allWebappDirs) {
+      const name = dir.split(/[/\\]/).pop();
+      run(`Web app install (${name})`, 'npm', ['install'], { cwd: dir });
+      run(`Web app build (${name})`, 'npm', ['run', 'build'], { cwd: dir });
+    }
+  }
+
   if (!skipDeploy) {
     run('Deploy metadata', 'sf', ['project', 'deploy', 'start', '--target-org', targetOrg], {
       timeout: 180000,
@@ -225,36 +394,115 @@ function main() {
     run('Prepare data (unique fields)', 'node', [prepareScript, '--data-dir', DATA_DIR], {
       cwd: ROOT,
     });
-    // Data import tree: if only DUPLICATES_DETECTED (org duplicate rules), warn and continue
+    // Normalize Lease__c Tenant refs to 1–15 so all refs resolve (Tenant__c.json has 15 records)
+    const leasePath = resolve(DATA_DIR, 'Lease__c.json');
+    if (existsSync(leasePath)) {
+      let leaseContent = readFileSync(leasePath, 'utf8');
+      leaseContent = leaseContent.replace(/@TenantRef(\d+)/g, (_m, n) => {
+        const k = ((parseInt(n, 10) - 1) % 15) + 1;
+        return `@TenantRef${k}`;
+      });
+      writeFileSync(leasePath, leaseContent);
+    }
+
+    // Delete existing records so every run inserts the full dataset without duplicate conflicts.
+    // Reverse plan order ensures children are removed before parents (FK safety).
+    console.log('\n--- Clean existing data for fresh import ---');
+    const planEntries = JSON.parse(readFileSync(DATA_PLAN, 'utf8'));
+    const sobjectsReversed = [...planEntries.map((e) => e.sobject)].reverse();
+    const tmpApex = resolve(ROOT, '.tmp-setup-delete.apex');
+    for (const sobject of sobjectsReversed) {
+      const apexCode = [
+        'try {',
+        `  List<SObject> recs = Database.query('SELECT Id FROM ${sobject} LIMIT 10000');`,
+        '  if (!recs.isEmpty()) {',
+        '    Database.delete(recs, false);',
+        '    Database.emptyRecycleBin(recs);',
+        '  }',
+        '} catch (Exception e) {',
+        '  // non-deletable records (e.g. Contact linked to Case) are skipped via allOrNone=false',
+        '}',
+      ].join('\n');
+      writeFileSync(tmpApex, apexCode);
+      spawnSync('sf', ['apex', 'run', '--target-org', targetOrg, '--file', tmpApex], {
+        cwd: ROOT,
+        stdio: 'pipe',
+        shell: true,
+        timeout: 60000,
+      });
+      console.log(`  ${sobject}: cleaned`);
+    }
+    if (existsSync(tmpApex)) unlinkSync(tmpApex);
+
+    // Import via Anonymous Apex with Database.DMLOptions.duplicateRuleHeader.allowSave = true.
+    // This bypasses both duplicate-rule blocks AND matching-service timeouts that the REST
+    // API headers (Sforce-Duplicate-Rule-Action) cannot override.
     console.log('\n--- Data import tree ---');
-    const importResult = spawnSync(
-      'sf',
-      ['data', 'import', 'tree', '--plan', DATA_PLAN, '--target-org', targetOrg, '--json'],
-      { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 120000 }
-    );
-    const out = (importResult.stdout?.toString() || '') + (importResult.stderr?.toString() || '');
-    if (importResult.status !== 0) {
-      let onlyDuplicates = false;
-      try {
-        const j = JSON.parse(out);
-        const errors = Array.isArray(j?.data) ? j.data : [];
-        onlyDuplicates =
-          errors.length > 0 &&
-          errors.every((e) => e.StatusCode === 'DUPLICATES_DETECTED' || e.statusCode === 'DUPLICATES_DETECTED');
-      } catch (_) {
-        onlyDuplicates = out.includes('DUPLICATES_DETECTED') && /Use one of these records\?/.test(out);
-      }
-      if (onlyDuplicates) {
-        console.warn(
-          'Data import hit org duplicate rules (e.g. Contact). Skipping import; rest of setup continues.'
-        );
-      } else {
-        process.stdout.write(importResult.stdout?.toString() || '');
-        process.stderr.write(importResult.stderr?.toString() || '');
-        console.error('\nSetup failed at step: Data import tree');
-        process.exit(importResult.status ?? 1);
+    const refMap = new Map();
+    const APEX_CHAR_LIMIT = 25000;
+    const APEX_MAX_BATCH = 200;
+
+    for (const entry of planEntries) {
+      for (const file of entry.files) {
+        const data = JSON.parse(readFileSync(resolve(DATA_DIR, file), 'utf8'));
+        const records = data.records || [];
+
+        for (const rec of records) {
+          for (const key of Object.keys(rec)) {
+            if (key === 'attributes') continue;
+            const val = rec[key];
+            if (typeof val === 'string' && val.startsWith('@')) {
+              const actual = refMap.get(val.slice(1));
+              if (actual) {
+                rec[key] = actual;
+              } else if (refMap.size > 0) {
+                console.warn(`    Warning: unresolved ref ${val} in ${file}`);
+              }
+            }
+          }
+        }
+
+        let imported = 0;
+        const sampleRec = records[0] || {};
+        const fieldsPerRec = Object.keys(sampleRec).filter((k) => k !== 'attributes').length;
+        const estCharsPerRec = 40 + fieldsPerRec * 55;
+        const batchSize = Math.min(APEX_MAX_BATCH, Math.max(5, Math.floor(APEX_CHAR_LIMIT / estCharsPerRec)));
+        for (let i = 0; i < records.length; i += batchSize) {
+          const batch = records.slice(i, i + batchSize);
+          const refIds = batch.map((r) => r.attributes?.referenceId || `_idx${i}`);
+          const apex = buildApexInsert(entry.sobject, batch, refIds);
+          writeFileSync(tmpApex, apex);
+          const apexResult = spawnSync(
+            'sf',
+            ['apex', 'run', '--target-org', targetOrg, '--file', tmpApex],
+            { cwd: ROOT, stdio: 'pipe', shell: true, timeout: 120000 }
+          );
+          const apexOut = apexResult.stdout?.toString() || '';
+          const apexErr = apexResult.stderr?.toString() || '';
+          if (apexResult.status !== 0 && !apexOut.includes('Compiled successfully')) {
+            console.error(`  ${entry.sobject}: apex execution failed`);
+            process.stderr.write(apexErr || apexOut);
+            process.exit(1);
+          }
+          const okMatches = [...apexOut.matchAll(/\|DEBUG\|REF:([^:\n]+):(\w+)/g)];
+          const errMatches = [...apexOut.matchAll(/\|DEBUG\|ERR:([^:\n]+):([^\n]+)/g)];
+          if (errMatches.length) {
+            for (const m of errMatches.slice(0, 5)) {
+              console.error(`    ${m[1]}: ${m[2].trim()}`);
+            }
+            if (errMatches.length > 5) console.error(`    ... and ${errMatches.length - 5} more`);
+            console.error(`\nSetup failed at step: Data import tree (${entry.sobject})`);
+            process.exit(1);
+          }
+          if (entry.saveRefs) {
+            for (const m of okMatches) refMap.set(m[1], m[2]);
+          }
+          imported += okMatches.length;
+        }
+        console.log(`  ${entry.sobject}: imported ${imported} records`);
       }
     }
+    if (existsSync(tmpApex)) unlinkSync(tmpApex);
   }
 
   if (!skipGraphql || !skipWebappBuild) {
@@ -279,4 +527,7 @@ function main() {
   }
 }
 
-main();
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-app-react-template-b2e-experimental",
-  "version": "1.92.0",
+  "version": "1.93.0",
   "description": "B2E template app (from BYO)",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",

package/dist/.a4drules/webapp-no-node-e.md

@@ -1,65 +0,0 @@
----
-description: No complex node -e one-liners — use temp .js files or sed/awk instead
-paths:
-  - "force-app/main/default/webapplications/**/*"
----
-
-# A4D Enforcement: No `node -e` One-Liners
-
-This project **forbids** using `node -e` (or `node -p`, `node --eval`) one-liners for any operation—file manipulation, string replacement, reading/writing configs, or shell automation.
-
-## Why This Exists
-
-Complex `node -e '...'` one-liners **silently break in Zsh** (the default macOS shell) because of:
-
-- **`!` (history expansion):** Zsh interprets `!` inside double quotes as history expansion, causing `event not found` errors or silent corruption.
-- **Backtick interpolation:** Template literals (`` ` ``) are interpreted as command substitution by the shell before Node.js ever sees them.
-- **Nested quoting:** Multi-line JS crammed into a single shell string requires fragile quote escaping that differs between Bash and Zsh.
-
-These failures are **silent and intermittent**—the command may appear to succeed while producing corrupt output.
-
-## What To Do Instead
-
-### For multi-line file edits or transforms
-
-1. **Write a temporary `.js` script**, run it, then delete it:
-
-```bash
-cat > /tmp/_transform.js << 'SCRIPT'
-const fs = require('fs');
-const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-data.name = 'my-app';
-fs.writeFileSync('package.json', JSON.stringify(data, null, 2) + '\n');
-SCRIPT
-node /tmp/_transform.js && rm /tmp/_transform.js
-```
-
-2. **Use `sed` or `awk`** for simple, single-pattern replacements with careful escaping:
-
-```bash
-sed -i '' 's/old-value/new-value/g' path/to/file
-```
-
-3. **Use `jq`** for JSON edits:
-
-```bash
-jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json
-```
-
-4. **Use the IDE/agent file-editing tools** (replace_in_file, write_to_file, StrReplace, Write) whenever available—these bypass the shell entirely.
-
-### For simple, truly one-line expressions
-
-A trivial `node -e "console.log(1+1)"` with no special characters is acceptable, but **if the expression contains any of these, use a temp file instead:**
-- Template literals (backticks)
-- `!` characters
-- Nested quotes
-- Multi-line strings
-- `fs` read/write operations
-
-## Violation Handling
-
-- If any prior step used a complex `node -e` one-liner, **revert and redo** using one of the approved methods above.
-- If a shell command fails with `event not found`, `unexpected token`, or produces garbled output, check for a `node -e` violation first.
-
-**Cross-reference:** This rule is also summarized in **webapp.md** (MUST FOLLOW #1). Both apply.