@salesforce/webapp-template-base-sfdx-project-experimental 1.103.2

package/.a4drules/skills/webapp-ui-ux/scripts/search.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, searchStack } from './core.js';
+import { generateDesignSystem } from './design_system.js';
+
+// ============ ARG PARSER ============
+
+function parseArgs(argv) {
+  const args = { query: null, maxResults: MAX_RESULTS, format: 'ascii' };
+  let i = 2;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--domain' || a === '-d') { args.domain = argv[++i]; }
+    else if (a === '--stack' || a === '-s') { args.stack = argv[++i]; }
+    else if (a === '--max-results' || a === '-n') { args.maxResults = parseInt(argv[++i], 10); }
+    else if (a === '--json') { args.json = true; }
+    else if (a === '--design-system' || a === '-ds') { args.designSystem = true; }
+    else if (a === '--project-name' || a === '-p') { args.projectName = argv[++i]; }
+    else if (a === '--format' || a === '-f') { args.format = argv[++i]; }
+    else if (a === '--persist') { args.persist = true; }
+    else if (a === '--page') { args.page = argv[++i]; }
+    else if (a === '--output-dir' || a === '-o') { args.outputDir = argv[++i]; }
+    else if (!a.startsWith('-') && !args.query) { args.query = a; }
+    i++;
+  }
+  return args;
+}
+
+// ============ FORMATTER ============
+
+function formatOutput(result) {
+  if (result.error) return `Error: ${result.error}`;
+
+  const lines = [];
+  if (result.stack) {
+    lines.push('## UI Pro Max Stack Guidelines');
+    lines.push(`**Stack:** ${result.stack} | **Query:** ${result.query}`);
+  } else {
+    lines.push('## UI Pro Max Search Results');
+    lines.push(`**Domain:** ${result.domain} | **Query:** ${result.query}`);
+  }
+  lines.push(`**Source:** ${result.file} | **Found:** ${result.count} results\n`);
+
+  (result.results || []).forEach((row, i) => {
+    lines.push(`### Result ${i + 1}`);
+    for (const [key, value] of Object.entries(row)) {
+      const v = String(value);
+      lines.push(`- **${key}:** ${v.length > 300 ? v.slice(0, 300) + '...' : v}`);
+    }
+    lines.push('');
+  });
+
+  return lines.join('\n');
+}
+
+// ============ MAIN ============
+
+const args = parseArgs(process.argv);
+
+if (!args.query) {
+  console.error('Usage: node search.js "<query>" [--domain <d>] [--stack <s>] [--design-system] [-p "Name"]');
+  console.error(`Domains: ${Object.keys(CSV_CONFIG).join(', ')}`);
+  console.error(`Stacks: ${AVAILABLE_STACKS.join(', ')}`);
+  process.exit(1);
+}
+
+if (args.designSystem) {
+  const result = generateDesignSystem(
+    args.query,
+    args.projectName,
+    args.format,
+    !!args.persist,
+    args.page || null,
+    args.outputDir || null
+  );
+  console.log(result);
+
+  if (args.persist) {
+    const slug = args.projectName ? args.projectName.toLowerCase().replace(/\s+/g, '-') : 'default';
+    console.log('\n' + '='.repeat(60));
+    console.log(`✅ Design system persisted to design-system/${slug}/`);
+    console.log(`   📄 design-system/${slug}/MASTER.md (Global Source of Truth)`);
+    if (args.page) {
+      const pageSlug = args.page.toLowerCase().replace(/\s+/g, '-');
+      console.log(`   📄 design-system/${slug}/pages/${pageSlug}.md (Page Overrides)`);
+    }
+    console.log('');
+    console.log(`📖 Usage: When building a page, check design-system/${slug}/pages/[page].md first.`);
+    console.log(`   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.`);
+    console.log('='.repeat(60));
+  }
+} else if (args.stack) {
+  const result = searchStack(args.query, args.stack, args.maxResults);
+  console.log(args.json ? JSON.stringify(result, null, 2) : formatOutput(result));
+} else {
+  const result = search(args.query, args.domain, args.maxResults);
+  console.log(args.json ? JSON.stringify(result, null, 2) : formatOutput(result));
+}

package/.a4drules/skills/webapp-unsplash-images/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: webapp-unsplash-images
+description: Adds high-quality Unsplash images to React pages. Use when the user asks to add a hero image, background image, placeholder image, stock photo, decorative image, or any Unsplash-sourced imagery to the web application.
+---
+
+# Unsplash Images
+
+## When to Use
+
+Use this skill when:
+- Adding hero banners, section backgrounds, or decorative images
+- The user asks for stock photography or placeholder images
+- A page needs visual appeal without custom assets
+
+---
+
+## Step 1 — Determine image purpose
+
+Identify what the image is for:
+
+- **Hero / banner** — full-width background behind text or a CTA
+- **Section accent** — smaller image alongside content (stats, testimonials, features)
+- **Card thumbnail** — image inside a card component
+- **Background texture** — subtle decorative background
+
+If unclear, ask:
+
+> "Where should the image appear — as a hero banner, a section accent, or a card thumbnail?"
+
+---
+
+## Step 2 — Select the right Unsplash URL format
+
+Read `implementation/usage.md` for the full reference. Key rules:
+
+1. **Always use `images.unsplash.com/photo-{id}` format** with explicit `w` and `q` parameters.
+2. **Never use `source.unsplash.com`** — it is deprecated and returns 404s.
+3. **Pin every image by its photo ID** — never rely on random or search endpoints.
+
+---
+
+## Step 3 — Validate image URLs
+
+Before using any Unsplash URL in code:
+
+1. Open the URL in a browser or fetch it to confirm it returns a 200 status and a valid image.
+2. If the URL returns a 404, redirect loop, or broken image, **discard it** and pick a different photo ID.
+3. Never ship a URL you have not personally verified.
+
+---
+
+## Step 4 — Implementation
+
+Read `implementation/usage.md` and follow the instructions there.
+
+---
+
+## Verification
+
+Before completing:
+
+1. Confirm every Unsplash URL loads a valid image (no 404, no redirect loops).
+2. Confirm `alt` text is set appropriately (empty `alt=""` for decorative, descriptive for meaningful).
+3. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.

package/.a4drules/skills/webapp-unsplash-images/implementation/usage.md

@@ -0,0 +1,159 @@
+# Unsplash Images — Implementation Guide
+
+## URL Format
+
+Always use the direct `images.unsplash.com` format with explicit sizing:
+
+```
+https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&q={QUALITY}
+```
+
+| Parameter | Purpose | Recommended values |
+|-----------|---------|--------------------|
+| `w` | Pixel width served by the CDN | `600` card, `800` section, `1200` hero, `1920` full-bleed |
+| `q` | JPEG quality 1–100 | `80`–`85` (good balance of quality vs size) |
+
+### Deprecated / broken formats — do NOT use
+
+| Format | Why it fails |
+|--------|-------------|
+| `source.unsplash.com/random` | Deprecated; returns 404 |
+| `source.unsplash.com/{WIDTH}x{HEIGHT}` | Deprecated; returns 404 |
+| `source.unsplash.com/featured/?{query}` | Deprecated; returns 404 |
+
+---
+
+## How to find a valid photo ID
+
+1. Go to [unsplash.com](https://unsplash.com) and search for the subject (e.g. "modern apartment").
+2. Open a photo. The URL will look like `unsplash.com/photos/{slug}-{PHOTO_ID}` or `unsplash.com/photos/{PHOTO_ID}`.
+3. The `PHOTO_ID` is the last hyphen-separated segment (e.g. `photo-1600596542815-ffad4c1539a9`).
+4. Build your URL: `https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1200&q=85`
+5. **Test the URL** in a browser before committing.
+
+---
+
+## Declaring image constants
+
+Define all Unsplash URLs as named constants at the top of the file. Never inline URLs in JSX.
+
+```tsx
+const HERO_IMAGE = "https://images.unsplash.com/photo-1600596542815-ffad4c1539a9?w=1200&q=85";
+const SECTION_IMAGE = "https://images.unsplash.com/photo-1514565131-fce0801e5785?w=800&q=85";
+```
+
+---
+
+## Rendering images in JSX
+
+### Hero / banner (decorative — empty alt)
+
+```tsx
+<div className="relative w-full overflow-hidden rounded-2xl">
+  <div className="relative aspect-[21/9] min-h-[280px] w-full md:aspect-[3/1]">
+    <img
+      src={HERO_IMAGE}
+      alt=""
+      className="h-full w-full object-cover"
+      loading="eager"
+      fetchPriority="high"
+    />
+    <div className="absolute inset-0 bg-black/40" />
+    <div className="absolute inset-0 flex flex-col items-center justify-center px-4">
+      {/* overlay content */}
+    </div>
+  </div>
+</div>
+```
+
+Key points:
+- `alt=""` for decorative images (screen readers skip them).
+- `loading="eager"` and `fetchPriority="high"` for above-the-fold heroes.
+- `object-cover` prevents stretching.
+- Semi-transparent overlay (`bg-black/40`) ensures text readability.
+
+### Section accent (meaningful — descriptive alt)
+
+```tsx
+<div className="relative min-h-[240px] overflow-hidden rounded-2xl">
+  <img src={SECTION_IMAGE} alt="City skyline at sunset" className="h-full w-full object-cover" />
+  <div className="absolute inset-0 bg-gradient-to-r from-black/20 to-transparent" />
+</div>
+```
+
+### Card thumbnail
+
+```tsx
+<div className="aspect-[4/3] overflow-hidden bg-muted">
+  <img
+    src={imageUrl}
+    alt=""
+    className="h-full w-full object-cover transition-transform hover:scale-105"
+    loading="lazy"
+  />
+</div>
+```
+
+Key points:
+- `loading="lazy"` for below-the-fold images.
+- `hover:scale-105` subtle zoom on hover.
+- `bg-muted` fallback color while loading.
+
+---
+
+## Fallback when no image is available
+
+Always provide a placeholder when the image URL may be null:
+
+```tsx
+{imageUrl ? (
+  <img src={imageUrl} alt="" className="h-full w-full object-cover" />
+) : (
+  <div className="flex h-full items-center justify-center text-muted-foreground">
+    No image
+  </div>
+)}
+```
+
+---
+
+## Content Security Policy (CSP)
+
+If the application enforces CSP headers, add `images.unsplash.com` to `img-src`:
+
+```
+img-src 'self' https://images.unsplash.com;
+```
+
+Other commonly needed origins for stock images:
+
+| Origin | Purpose |
+|--------|---------|
+| `images.unsplash.com` | Unsplash photos |
+| `images.pexels.com` | Pexels photos |
+| `fonts.googleapis.com` | Google Fonts CSS |
+| `fonts.gstatic.com` | Google Fonts files |
+
+---
+
+## Accessibility checklist
+
+- [ ] Decorative images have `alt=""`
+- [ ] Meaningful images have descriptive `alt` text
+- [ ] Hero images use `loading="eager"` and `fetchPriority="high"`
+- [ ] Below-fold images use `loading="lazy"`
+- [ ] Text over images has sufficient contrast (use overlay like `bg-black/40`)
+- [ ] All URLs verified to return a valid image (no 404s)
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `source.unsplash.com` | Replace with `images.unsplash.com/photo-{id}?w=…&q=…` |
+| Hardcoding an unverified URL | Open URL in browser first; replace if broken |
+| Missing `w` parameter | Always set width — CDN returns full-res (5000px+) otherwise |
+| `loading="lazy"` on hero | Use `loading="eager"` for above-the-fold images |
+| No fallback for nullable URLs | Wrap in conditional with placeholder div |
+| Inline URLs in JSX | Extract to named constants at file top |

package/.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/.a4drules/webapp-react-code-quality.md

@@ -0,0 +1,136 @@
+---
+description: Code quality and build validation standards
+paths:
+  - "**/webapplications/**/*"
+---
+
+# Code Quality & Build Validation
+
+Enforces ESLint, TypeScript, and build validation for consistent, maintainable code.
+
+## MANDATORY Quality Gates
+
+**Before completing any coding session** (from the web app directory `force-app/main/default/webapplications/<appName>/`):
+
+```bash
+npm run lint   # MUST result in 0 errors
+npm run build  # MUST succeed (includes TypeScript check)
+```
+
+## Requirements
+
+**Must Pass:**
+- `npm run build` completes successfully
+- No TypeScript compilation errors
+- No critical ESLint errors (0 errors)
+
+**Can Be Warnings:**
+- ESLint warnings (fix when convenient)
+- Minor TypeScript warnings
+
+## Key Commands
+
+```bash
+npm run dev    # Start development server (vite)
+npm run lint   # Run ESLint
+npm run build  # TypeScript + Vite build; check deployment readiness
+```
+
+## Error Priority
+
+**Fix Immediately:**
+- TypeScript compilation errors
+- Import/export errors
+- Syntax errors
+
+**Fix When Convenient:**
+- ESLint warnings
+- Unused variables
+
+## Import Order (MANDATORY)
+
+```typescript
+// 1. React ecosystem
+import { useState, useEffect } from 'react';
+
+// 2. External libraries (alphabetical)
+import clsx from 'clsx';
+
+// 3. UI components (alphabetical)
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+
+// 4. Internal utilities (alphabetical)
+import { useAuth } from '../hooks/useAuth';
+import { formatDate } from '../utils/dateUtils';
+
+// 5. Relative imports
+import { ComponentA } from './ComponentA';
+
+// 6. Type imports (separate, at end)
+import type { User, ApiResponse } from '../types';
+```
+
+## Naming Conventions
+
+```typescript
+// PascalCase: Components, classes
+const UserProfile = () => {};
+
+// camelCase: Variables, functions, properties
+const userName = 'john';
+const fetchUserData = async () => {};
+
+// SCREAMING_SNAKE_CASE: Constants
+const API_BASE_URL = 'https://api.example.com';
+
+// kebab-case: Files
+// user-profile.tsx, api-client.ts
+```
+
+## React Component Structure
+
+```typescript
+interface ComponentProps {
+  // Props interface first
+}
+
+const Component: React.FC<ComponentProps> = ({ prop1, prop2 }) => {
+  // 1. Hooks
+  // 2. Computed values
+  // 3. Event handlers
+  // 4. JSX return
+
+  return <div />;
+};
+
+export default Component;
+```
+
+## Anti-Patterns (FORBIDDEN)
+
+```typescript
+// NEVER disable ESLint without justification
+// eslint-disable-next-line
+
+// NEVER mutate state directly
+state.items.push(newItem); // Wrong
+setItems(prev => [...prev, newItem]); // Correct
+
+// NEVER use magic numbers/strings
+setTimeout(() => {}, 5000); // Wrong
+const DEBOUNCE_DELAY = 5000; // Correct
+```
+
+## Troubleshooting
+
+**Import Errors:**
+```bash
+npm install  # Check missing dependencies
+# Verify: file exists, case sensitivity, export/import match
+```
+
+**Build Failures:**
+1. Run `npm run lint` to identify issues
+2. Fix TypeScript/ESLint errors
+3. Retry `npm run build`