@schandlergarcia/sf-web-components 1.9.86 → 1.9.88

package/.a4drules/skills/command-center-builder/SKILL.md

@@ -398,19 +398,27 @@ Define schemas outside component body. Always `required: true` on mandatory fiel
 
 ## AI Chat & Agent
 
-Two components for agent integration:
+Two pieces for agent integration — a **ChatBar** component and the **`useEvaAgent` hook** (Agent REST API):
 
 - **`ChatBar`** — command-palette strip for suggested prompts. Place between the hero map and data panels (full-width, `px-4 pt-4`), NOT in the header. Always provide 3–5 `suggestions`.
-- **`AgentforceConversationClient`** — the real Salesforce agent. Import from `@/components/AgentforceConversationClient` and pass the agent ID. Renders as a floating widget.
+- **`useEvaAgent`** — pre-installed hook at `src/hooks/useEvaAgent.ts`. Handles OAuth → session → messages → cleanup via the Agentforce Agent REST API. Config is in `src/config/agentApi.ts`. Vite proxy rules in `vite.config.ts` forward requests.
+
+> **Do NOT use `AgentforceConversationClient`** (the iframe widget). We use the Agent REST API via `useEvaAgent`.
+> **Do NOT create wrapper hooks** (useEvaChatAdapter, useDisruptionAlerts, etc.). Use `useEvaAgent` directly.
+> **Do NOT create `.env` or `.env.local` files** — config is hardcoded in `src/config/agentApi.ts`.
 
 ```tsx
-import { AgentforceConversationClient } from "@/components/AgentforceConversationClient";
+import useEvaAgent from "@/hooks/useEvaAgent";
+
+const { messages, isReady, isSending, connect, sendMessage } = useEvaAgent();
+useEffect(() => { connect(); }, [connect]);
 
-<AgentforceConversationClient agentId="0Xxa5000000relhCAA" agentLabel="Eva" />
+const handleChat = (text: string) => {
+  sendMessage(text);
+  return { text: `Looking into: "${text}"…` };
+};
 ```
 
-- Return `components` for structured data — never markdown tables in text
-- Always set height on `ChatPanel`
 - Extract `onSend` handlers to module scope when shared
 
 ## Tables

package/.a4drules/skills/component-library/SKILL.md

@@ -672,7 +672,7 @@ Dropdown select. Value `"all"` skips filtering.
 ## Data Utilities
 
 ### DataModeToggle
-**When:** Place in the app header to let users switch between sample and live data.
+> ⚠️ **Do NOT use in the Engine Command Center dashboard.** The Engine dashboard controls data mode via `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` — there is no UI toggle. Only use `DataModeToggle` in non-Engine dashboards that explicitly need a manual toggle.
 
 ```jsx
 <DataModeToggle className="ml-4" />

package/.a4drules/skills/component-library/chat-data.md

@@ -54,7 +54,7 @@ Wraps app. Provides `useDataMode()` → `{ mode, isSample, isLive, toggle, setMo
 ## Data Utilities
 
 ### DataModeToggle
-**When:** Place in the app header to let users switch between sample and live data.
+> ⚠️ **Do NOT use in the Engine Command Center dashboard.** The Engine dashboard controls data mode via `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` — there is no UI toggle. Only use `DataModeToggle` in non-Engine dashboards that explicitly need a manual toggle.
 
 ```jsx
 <DataModeToggle className="ml-4" />

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.88] - 2026-04-07
+
+### Fixed
+- **Postinstall `.a4drules` copy** — now copies all root-level `.md` files (`webapp-ui.md`, `webapp-data.md`, `validation-requirements.md`, `RULES.md`) and all subdirectories (`skills/`, `features/`, `troubleshooting/`), not just `skills/` and `features/`. Ensures the full build guide reaches consuming projects.
+- **Postinstall vite proxy injection** — when `vite.config.ts` already exists, the postinstall now checks for and injects the Agent API proxy rules (`/sf-oauth`, `/sf-agent`) if they're missing, rather than silently skipping.
+- **Reset script `.a4drules` restore** — the reset script now force-copies every `.md` file from the package's `.a4drules` to the project root, preventing stale stubs from persisting across resets.
+
+## [1.9.87] - 2026-04-07
+
+### Changed
+- **SKILL.md AI Chat section** — replaced `AgentforceConversationClient` instructions with `useEvaAgent` hook usage and explicit prohibitions against iframe widget, wrapper hooks, and .env files.
+- **Component library DataModeToggle docs** — added warning that DataModeToggle must NOT be used in the Engine Command Center dashboard (both SKILL.md and chat-data.md).
+
 ## [1.9.86] - 2026-04-07
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.86",
+  "version": "1.9.88",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/postinstall.mjs

@@ -429,7 +429,46 @@ if (fs.existsSync(viteConfigTemplatePath) && !fs.existsSync(viteConfigPath)) {
     console.error(`  ✗ Failed to install vite.config.ts: ${error.message}`);
   }
 } else if (fs.existsSync(viteConfigPath)) {
-  console.log('  ℹ vite.config.ts already exists (not overwriting)');
+  // Ensure Agent API proxy rules exist even in pre-existing vite.config.ts
+  try {
+    const existing = fs.readFileSync(viteConfigPath, 'utf-8');
+    if (!existing.includes('/sf-oauth') || !existing.includes("api.salesforce.com")) {
+      const proxyBlock = `
+    // Proxy Agentforce Agent API calls through the dev server to avoid CORS.
+    // /sf-oauth/* → Salesforce org (for OAuth client-credentials token)
+    // /sf-agent/* → Agent API base (for session + message calls)
+    server: {
+      proxy: {
+        '/sf-oauth': {
+          target: 'https://tdx26-keynote-org-1com.my.salesforce.com',
+          changeOrigin: true,
+          rewrite: (p: string) => p.replace(/^\\/sf-oauth/, ''),
+        },
+        '/sf-agent': {
+          target: 'https://api.salesforce.com',
+          changeOrigin: true,
+          rewrite: (p: string) => p.replace(/^\\/sf-agent/, ''),
+        },
+      },
+    },
+`;
+      // Insert before the build: { section if it exists
+      if (existing.includes('build: {') && !existing.includes('server: {')) {
+        const updated = existing.replace(
+          /(\s*)(\/\/.*Build|build:\s*\{)/,
+          proxyBlock + '\n$1$2'
+        );
+        if (updated !== existing) {
+          fs.writeFileSync(viteConfigPath, updated, 'utf-8');
+          console.log('  ✓ Added Agent API proxy rules to existing vite.config.ts');
+        }
+      }
+    } else {
+      console.log('  ℹ vite.config.ts already has proxy rules');
+    }
+  } catch {
+    // Non-critical — proxy can be added manually
+  }
 }
 
 // Copy dataStrategy.ts template
@@ -501,35 +540,48 @@ if (fs.existsSync(packageJsonPath)) {
 
 // Copy .a4drules from package to project root (so AI assistants can discover them)
 const packageA4dRules = path.join(packageRoot, '.a4drules');
-const projectRootA4dRules = path.join(cwd, '../../../../../.a4drules'); // Go up from webapp to project root
 
 if (fs.existsSync(packageA4dRules)) {
   console.log('\n📋 Copying AI assistant rules to project root...\n');
 
-  // Resolve to absolute path
   const projectRootPath = path.resolve(cwd, '../../../../../');
   const targetA4dRules = path.join(projectRootPath, '.a4drules');
 
-  // Create .a4drules if it doesn't exist
   if (!fs.existsSync(targetA4dRules)) {
     fs.mkdirSync(targetA4dRules, { recursive: true });
   }
 
-  // Copy skills directory
-  const skillsSource = path.join(packageA4dRules, 'skills');
-  const skillsTarget = path.join(targetA4dRules, 'skills');
-  if (fs.existsSync(skillsSource)) {
-    const skillsCopied = copyDirectoryRecursive(skillsSource, skillsTarget);
-    console.log(`  ✓ Copied ${skillsCopied} skill files`);
+  let totalA4dCopied = 0;
+
+  // Force-copy root-level .md files first
+  const rootFiles = fs.readdirSync(packageA4dRules).filter(f => f.endsWith('.md'));
+  for (const file of rootFiles) {
+    try {
+      fs.copyFileSync(path.join(packageA4dRules, file), path.join(targetA4dRules, file));
+      totalA4dCopied++;
+    } catch (error) {
+      console.error(`  ✗ Failed to copy ${file}: ${error.message}`);
+    }
+  }
+  if (rootFiles.length > 0) {
+    console.log(`  ✓ Copied ${rootFiles.length} root rule files`);
   }
 
-  // Copy features directory
-  const featuresSource = path.join(packageA4dRules, 'features');
-  const featuresTarget = path.join(targetA4dRules, 'features');
-  if (fs.existsSync(featuresSource)) {
-    const featuresCopied = copyDirectoryRecursive(featuresSource, featuresTarget);
-    console.log(`  ✓ Copied ${featuresCopied} feature rule files`);
+  // Copy all subdirectories (skills, features, troubleshooting)
+  const subdirs = fs.readdirSync(packageA4dRules).filter(d => {
+    const full = path.join(packageA4dRules, d);
+    return fs.statSync(full).isDirectory();
+  });
+
+  for (const subdir of subdirs) {
+    const src = path.join(packageA4dRules, subdir);
+    const dst = path.join(targetA4dRules, subdir);
+    const copied = copyDirectoryRecursive(src, dst);
+    totalA4dCopied += copied;
+    console.log(`  ✓ Copied ${copied} files from ${subdir}/`);
   }
+
+  console.log(`  📋 Total: ${totalA4dCopied} rule files installed`);
 }
 
 // Migrate any dashboards from old location (src/components/pages/) to new location (src/pages/)

package/scripts/reset-command-center.sh

@@ -27,6 +27,7 @@ else
 fi
 
 cd "$ROOT"
+ROOT_ABS="$(cd "$ROOT" && pwd)"
 
 echo ""
 echo "╔════════════════════════════════════════════════╗"
@@ -799,15 +800,53 @@ else
   echo "  ⚠ Skipped logo (package logo not found)"
 fi
 
+# ── Restore .a4drules to project root ─────────────────────────────────────────
+
+echo "→ Restoring AI assistant rules (.a4drules)..."
+
+# Detect package .a4drules location
+PACKAGE_A4D=""
+if [ -d "node_modules/@schandlergarcia/sf-web-components/.a4drules" ]; then
+  PACKAGE_A4D="node_modules/@schandlergarcia/sf-web-components/.a4drules"
+elif [ -d "$SCRIPT_DIR/../.a4drules" ]; then
+  PACKAGE_A4D="$SCRIPT_DIR/../.a4drules"
+fi
+
+if [ -n "$PACKAGE_A4D" ]; then
+  # Resolve project root (5 levels up from webapp, or 1 level up from package source)
+  PROJECT_ROOT=""
+  if [[ "$ROOT_ABS" == */force-app/main/default/* ]]; then
+    PROJECT_ROOT="${ROOT_ABS%%/force-app/main/default/*}"
+  else
+    PROJECT_ROOT="$ROOT/.."
+  fi
+
+  if [ -n "$PROJECT_ROOT" ] && [ -d "$PROJECT_ROOT" ]; then
+    TARGET_A4D="$PROJECT_ROOT/.a4drules"
+    a4d_copied=0
+
+    # Force-copy every .md file individually (cp -R doesn't always overwrite)
+    while IFS= read -r src_file; do
+      rel="${src_file#$PACKAGE_A4D/}"
+      dst="$TARGET_A4D/$rel"
+      mkdir -p "$(dirname "$dst")"
+      cp -f "$src_file" "$dst"
+      a4d_copied=$((a4d_copied + 1))
+    done < <(find "$PACKAGE_A4D" -name "*.md" -type f)
+
+    echo "  ✓ Restored $a4d_copied rule files to $TARGET_A4D"
+  fi
+else
+  echo "  ⚠ Skipped .a4drules (package rules not found)"
+fi
+echo ""
+
 # ── Clean Salesforce metadata created during the demo ────────────────────────
 
 SFDX_DEFAULT=""
 
 # The webapp lives inside force-app/main/default/uiBundles/..., so extract
-# the SFDX default directory from our own path first. Only fall back to
-# searching child directories if the pattern doesn't match (standalone app).
-ROOT_ABS="$(cd "$ROOT" && pwd)"
-
+# the SFDX default directory from our own path first.
 if [[ "$ROOT_ABS" == */force-app/main/default/* ]]; then
   SFDX_DEFAULT="${ROOT_ABS%%/force-app/main/default/*}/force-app/main/default"
 fi
@@ -872,6 +911,7 @@ echo "║     • Agent API config (src/config/agentApi.ts)║"
 echo "║     • Data strategy (ENABLE_SAMPLE_DATA_CACHE) ║"
 echo "║     • GraphQL schema + PRD + logo              ║"
 echo "║     • Component library + theme providers      ║"
+echo "║     • AI assistant rules (.a4drules)          ║"
 echo "║                                                ║"
 echo "║   Cleaned:                                     ║"
 echo "║     • Apex classes (force-app classes/)         ║"