@salesforce/afv-skills 1.5.0 → 1.5.2

package/skills/{using-webapp-salesforce-data → using-ui-bundle-salesforce-data/scripts}/graphql-search.sh

@@ -1,20 +1,23 @@
 #!/usr/bin/env bash
+set -euo pipefail  # exit on error (-e), undefined vars (-u), and propagate pipeline failures (-o pipefail)
 # graphql-search.sh — Look up one or more Salesforce entities in schema.graphql.
 #
 # Run from the SFDX project root (where schema.graphql lives):
-#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
-#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
+#   bash scripts/graphql-search.sh Account
+#   bash scripts/graphql-search.sh Account Contact Opportunity
 #
 # Pass a custom schema path with -s / --schema:
-#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh -s /path/to/schema.graphql Account
-#   bash .a4drules/skills/using-salesforce-data/graphql-search.sh --schema ./other/schema.graphql Account Contact
+#   bash scripts/graphql-search.sh -s /path/to/schema.graphql Account
+#   bash scripts/graphql-search.sh --schema ./other/schema.graphql Account Contact
 #
 # Output sections per entity:
-#   1. Type definition   — all fields and relationships
-#   2. Filter options    — <Entity>_Filter input (for `where:`)
-#   3. Sort options      — <Entity>_OrderBy input (for `orderBy:`)
-#   4. Create input      — <Entity>CreateRepresentation (for create mutations)
-#   5. Update input      — <Entity>UpdateRepresentation (for update mutations)
+#   1. Type definition          — all fields and relationships
+#   2. Filter options           — <Entity>_Filter input (for `where:`)
+#   3. Sort options             — <Entity>_OrderBy input (for `orderBy:`)
+#   4. Create mutation wrapper  — <Entity>CreateInput
+#   5. Create mutation fields   — <Entity>CreateRepresentation (for create mutations)
+#   6. Update mutation wrapper  — <Entity>UpdateInput
+#   7. Update mutation fields   — <Entity>UpdateRepresentation (for update mutations)
 
 SCHEMA="./schema.graphql"
 
@@ -57,8 +60,21 @@ if [ ! -f "$SCHEMA" ]; then
   echo "ERROR: schema.graphql not found at $SCHEMA"
   echo "  Make sure you are running from the SFDX project root, or pass the path explicitly:"
   echo "    bash $0 --schema <path/to/schema.graphql> <EntityName>"
-  echo "  If the file is missing entirely, generate it from the webapp dir:"
-  echo "    cd force-app/main/default/webapplications/<app-name> && npm run graphql:schema"
+  echo "  If the file is missing entirely, generate it from the UI bundle dir:"
+  echo "    cd force-app/main/default/uiBundles/<app-name> && npm run graphql:schema"
+  exit 1
+fi
+
+if [ ! -r "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql is not readable at $SCHEMA"
+  echo "  Check file permissions: ls -la $SCHEMA"
+  exit 1
+fi
+
+if [ ! -s "$SCHEMA" ]; then
+  echo "ERROR: schema.graphql is empty at $SCHEMA"
+  echo "  Regenerate it from the UI bundle dir:"
+  echo "    cd force-app/main/default/uiBundles/<app-name> && npm run graphql:schema"
   exit 1
 fi
 
@@ -72,68 +88,104 @@ extract_block() {
   local max_lines="$3"
 
   local match
-  match=$(grep -nE "$pattern" "$SCHEMA" | head -1)
+  local grep_exit=0
+  match=$(grep -nE "$pattern" "$SCHEMA" | head -1) || grep_exit=$?
+
+  if [ "$grep_exit" -eq 2 ]; then
+    echo "  ERROR: grep failed on pattern: $pattern" >&2
+    return 1
+  fi
 
   if [ -z "$match" ]; then
     echo "  (not found: $pattern)"
-    return
+    return 3
   fi
 
   echo "### $label"
   grep -E "$pattern" "$SCHEMA" -A "$max_lines" | \
     awk '/^\}$/{print; exit} {print}' | \
-    head -n "$max_lines"
+    head -n "$max_lines" || true
   echo ""
 }
 
 # ── Main loop ────────────────────────────────────────────────────────────────
 
 for ENTITY in "$@"; do
+  # Validate entity name: must be a valid PascalCase identifier (letters, digits, underscores)
+  if [[ ! "$ENTITY" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    echo "ERROR: Invalid entity name: '$ENTITY'"
+    echo "  Entity names must start with a letter or underscore, followed by letters, digits, or underscores."
+    echo "  Examples: Account, My_Custom_Object__c"
+    continue
+  fi
+
   echo ""
   echo "======================================================================"
   echo "  SCHEMA LOOKUP: $ENTITY"
   echo "======================================================================"
   echo ""
 
+  found=0
+
+  # Helper: call extract_block, track matches, surface errors
+  try_extract() {
+    local rc=0
+    extract_block "$@" || rc=$?
+    if [ "$rc" -eq 0 ]; then
+      found=$((found + 1))
+    elif [ "$rc" -eq 1 ]; then
+      echo "  Aborting lookup for '$ENTITY' due to grep error" >&2
+    fi
+    # rc=3 is not-found — continue silently (already printed by extract_block)
+  }
+
   # 1. Type definition — all fields and relationships
-  extract_block \
+  try_extract \
     "Type definition — fields and relationships" \
     "^type ${ENTITY} implements Record" \
     200
 
   # 2. Filter input — used in `where:` arguments
-  extract_block \
+  try_extract \
     "Filter options — use in where: { ... }" \
     "^input ${ENTITY}_Filter" \
     100
 
   # 3. OrderBy input — used in `orderBy:` arguments
-  extract_block \
+  try_extract \
     "Sort options — use in orderBy: { ... }" \
     "^input ${ENTITY}_OrderBy" \
     60
 
-  # 4. Create mutation inputs
-  extract_block \
+  # 4. Create mutation wrapper
+  try_extract \
     "Create mutation wrapper — ${ENTITY}CreateInput" \
     "^input ${ENTITY}CreateInput" \
     10
 
-  extract_block \
+  # 5. Create mutation fields
+  try_extract \
     "Create mutation fields — ${ENTITY}CreateRepresentation" \
     "^input ${ENTITY}CreateRepresentation" \
     100
 
-  # 5. Update mutation inputs
-  extract_block \
+  # 6. Update mutation wrapper
+  try_extract \
     "Update mutation wrapper — ${ENTITY}UpdateInput" \
     "^input ${ENTITY}UpdateInput" \
     10
 
-  extract_block \
+  # 7. Update mutation fields
+  try_extract \
     "Update mutation fields — ${ENTITY}UpdateRepresentation" \
     "^input ${ENTITY}UpdateRepresentation" \
     100
 
+  if [ "$found" -eq 0 ]; then
+    echo "WARNING: No schema entries found for '$ENTITY'."
+    echo "  - Names are PascalCase (e.g., 'Account' not 'account')"
+    echo "  - Custom objects may need deployment first"
+  fi
+
   echo ""
 done

package/skills/building-webapp-data-visualization/SKILL.md

@@ -1,72 +0,0 @@
----
-name: building-webapp-data-visualization
-description: "Adds data visualization components (charts, stat cards, KPI metrics) to React pages using Recharts. Use when the user asks to add a chart, graph, donut chart, pie chart, bar chart, stat card, KPI metric, dashboard visualization, or analytics component to the web application."
----
-
-# Data Visualization
-
-## When to Use
-
-Use this skill when:
-- Adding charts (donut, pie, bar, line, area) to a dashboard or analytics page
-- Displaying KPI/metric stat cards with trend indicators
-- Building a dashboard layout with mixed chart types and summary cards
-
----
-
-## Step 1 — Determine the visualization type
-
-Identify what the user needs:
-
-- **Donut / pie chart** — categorical breakdown (e.g. issue types, status distribution)
-- **Bar chart** — comparison across categories or time periods
-- **Line / area chart** — trends over time
-- **Stat card** — single KPI metric with optional trend indicator
-- **Combined dashboard** — stat cards + one or more charts
-
-If unclear, ask:
-
-> "What data should the chart display, and would a donut chart, bar chart, line chart, or stat cards work best?"
-
----
-
-## Step 2 — Install dependencies
-
-All chart types in this skill use **recharts**. Install once from the web app directory:
-
-```bash
-npm install recharts
-```
-
-Recharts is built on D3 and provides declarative React components. No additional CSS is needed.
-
----
-
-## Step 3 — Choose implementation path
-
-Read the corresponding guide:
-
-- **Bar chart** — read `implementation/bar-line-chart.md` (categorical data)
-- **Line / area chart** — read `implementation/bar-line-chart.md` (time-series data)
-- **Donut / pie chart** — read `implementation/donut-chart.md`
-- **Stat card with trend** — read `implementation/stat-card.md`
-- **Dashboard layout** — read `implementation/dashboard-layout.md`
-
----
-
-## Verification
-
-Before completing:
-
-1. Chart renders with correct data and colors.
-2. Chart is responsive (resizes with container).
-3. Legend labels match the data categories.
-4. Stat card trends display correct positive/negative indicators.
-5. 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/skills/building-webapp-data-visualization/implementation/bar-line-chart.md

@@ -1,316 +0,0 @@
-# Bar & Line / Area Chart — Implementation Guide
-
-Requires **recharts** (install from the web app directory; see SKILL.md Step 2).
-
----
-
-## Data shapes
-
-### Time-series (line / area chart)
-
-Use when data represents a trend over time or ordered sequence.
-
-```ts
-interface TimeSeriesDataPoint {
-  x: string;   // date or label on the x-axis
-  y: number;   // numeric value
-}
-```
-
-Map raw fields to this shape: e.g. `date` → `x`, `revenue` → `y`.
-
-### Categorical (bar chart)
-
-Use when data compares discrete categories.
-
-```ts
-interface CategoricalDataPoint {
-  name: string;   // category label
-  value: number;  // numeric value
-}
-```
-
-Map raw fields to this shape: e.g. `product` → `name`, `sales` → `value`.
-
-### How to decide
-
-| Signal | Type |
-|--------|------|
-| "over time", "trend", date-like keys | Time-series → line chart |
-| "by category", "by X", label-like keys | Categorical → bar chart |
-
----
-
-## Theme colors
-
-Pick a theme based on the data's sentiment:
-
-| Theme | Stroke / Fill | When to use |
-|-------|---------------|-------------|
-| `green` | `#22c55e` | Growth, gain, positive trend |
-| `red` | `#ef4444` | Decline, loss, negative trend |
-| `neutral` | `#6366f1` | Default or mixed data |
-
-Define colors as constants — do not use inline hex values.
-
-```ts
-const THEME_COLORS = {
-  red: "#ef4444",
-  green: "#22c55e",
-  neutral: "#6366f1",
-} as const;
-
-type ChartTheme = keyof typeof THEME_COLORS;
-```
-
----
-
-## Line chart component
-
-Create at `components/LineChart.tsx` (or colocate with the page):
-
-```tsx
-import React from "react";
-import {
-  LineChart as RechartsLineChart,
-  Line,
-  XAxis,
-  YAxis,
-  CartesianGrid,
-  Tooltip,
-  Legend,
-  ResponsiveContainer,
-} from "recharts";
-
-const THEME_COLORS = {
-  red: "#ef4444",
-  green: "#22c55e",
-  neutral: "#6366f1",
-} as const;
-
-type ChartTheme = keyof typeof THEME_COLORS;
-
-interface TimeSeriesDataPoint {
-  x: string;
-  y: number;
-}
-
-interface TimeSeriesChartProps {
-  data: TimeSeriesDataPoint[];
-  theme?: ChartTheme;
-  title?: string;
-  className?: string;
-}
-
-export function TimeSeriesChart({
-  data,
-  theme = "neutral",
-  title,
-  className = "",
-}: TimeSeriesChartProps) {
-  if (data.length === 0) {
-    return <p className="text-muted-foreground text-center py-8">No data to display</p>;
-  }
-
-  const color = THEME_COLORS[theme];
-
-  return (
-    <div className={className}>
-      {title && (
-        <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
-          {title}
-        </h3>
-      )}
-      <ResponsiveContainer width="100%" height={300}>
-        <RechartsLineChart data={data}>
-          <CartesianGrid strokeDasharray="3 3" />
-          <XAxis dataKey="x" />
-          <YAxis />
-          <Tooltip />
-          <Legend />
-          <Line type="monotone" dataKey="y" stroke={color} strokeWidth={2} dot={false} />
-        </RechartsLineChart>
-      </ResponsiveContainer>
-    </div>
-  );
-}
-```
-
----
-
-## Bar chart component
-
-Create at `components/BarChart.tsx` (or colocate with the page):
-
-```tsx
-import React from "react";
-import {
-  BarChart as RechartsBarChart,
-  Bar,
-  XAxis,
-  YAxis,
-  CartesianGrid,
-  Tooltip,
-  Legend,
-  ResponsiveContainer,
-} from "recharts";
-
-const THEME_COLORS = {
-  red: "#ef4444",
-  green: "#22c55e",
-  neutral: "#6366f1",
-} as const;
-
-type ChartTheme = keyof typeof THEME_COLORS;
-
-interface CategoricalDataPoint {
-  name: string;
-  value: number;
-}
-
-interface CategoricalChartProps {
-  data: CategoricalDataPoint[];
-  theme?: ChartTheme;
-  title?: string;
-  className?: string;
-}
-
-export function CategoricalChart({
-  data,
-  theme = "neutral",
-  title,
-  className = "",
-}: CategoricalChartProps) {
-  if (data.length === 0) {
-    return <p className="text-muted-foreground text-center py-8">No data to display</p>;
-  }
-
-  const color = THEME_COLORS[theme];
-
-  return (
-    <div className={className}>
-      {title && (
-        <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
-          {title}
-        </h3>
-      )}
-      <ResponsiveContainer width="100%" height={300}>
-        <RechartsBarChart data={data}>
-          <CartesianGrid strokeDasharray="3 3" />
-          <XAxis dataKey="name" />
-          <YAxis />
-          <Tooltip />
-          <Legend />
-          <Bar dataKey="value" fill={color} radius={[4, 4, 0, 0]} />
-        </RechartsBarChart>
-      </ResponsiveContainer>
-    </div>
-  );
-}
-```
-
----
-
-## Area chart variant
-
-For a filled area chart (useful for volume-over-time), swap `Line` for `Area`:
-
-```tsx
-import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from "recharts";
-
-<ResponsiveContainer width="100%" height={300}>
-  <AreaChart data={data}>
-    <CartesianGrid strokeDasharray="3 3" />
-    <XAxis dataKey="x" />
-    <YAxis />
-    <Tooltip />
-    <Area type="monotone" dataKey="y" stroke={color} fill={color} fillOpacity={0.2} />
-  </AreaChart>
-</ResponsiveContainer>
-```
-
----
-
-## Chart container wrapper
-
-Wrap any chart in a styled card for consistent spacing:
-
-```tsx
-import { Card } from "@/components/ui/card";
-
-interface ChartContainerProps {
-  children: React.ReactNode;
-  className?: string;
-}
-
-export function ChartContainer({ children, className = "" }: ChartContainerProps) {
-  return (
-    <Card className={`p-4 border-gray-200 shadow-sm ${className}`}>
-      {children}
-    </Card>
-  );
-}
-```
-
-Usage:
-
-```tsx
-<ChartContainer>
-  <TimeSeriesChart data={monthlyData} theme="green" title="Monthly Revenue" />
-</ChartContainer>
-```
-
----
-
-## Preparing raw data
-
-Map API responses to the expected shape before passing to the chart:
-
-```tsx
-const timeSeriesData = useMemo(
-  () => apiRecords.map((r) => ({ x: r.date, y: r.revenue })),
-  [apiRecords],
-);
-
-const categoricalData = useMemo(
-  () => apiRecords.map((r) => ({ name: r.product, value: r.sales })),
-  [apiRecords],
-);
-```
-
----
-
-## Key Recharts concepts
-
-| Component | Purpose |
-|-----------|---------|
-| `ResponsiveContainer` | Wraps chart to fill parent width |
-| `CartesianGrid` | Background grid lines |
-| `XAxis` / `YAxis` | Axis labels; `dataKey` maps to the data field |
-| `Tooltip` | Hover info |
-| `Legend` | Series labels |
-| `Line` | Line series; `type="monotone"` for smooth curves |
-| `Bar` | Bar series; `radius` rounds top corners |
-| `Area` | Filled area; `fillOpacity` controls transparency |
-
----
-
-## Accessibility
-
-- Always include a text legend (not just colors).
-- Chart should be wrapped in a section with a visible heading.
-- For critical data, provide a text summary or table alternative.
-- Use sufficient color contrast between the chart stroke/fill and background.
-- Consider `prefers-reduced-motion` for chart animations.
-
----
-
-## Common mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| Missing `ResponsiveContainer` | Chart won't resize; always wrap |
-| Fixed width/height on chart | Let `ResponsiveContainer` control sizing |
-| No empty-data handling | Show "No data" message when `data.length === 0` |
-| Inline colors | Extract to `THEME_COLORS` constant |
-| Using raw Recharts for every chart type | Use `DonutChart` (see `donut-chart.md`) for pie/donut |