@salesforce/afv-skills 1.60.0 → 1.62.0

package/skills/crm-analytics-wave-generate/references/r3-node-schema.md

@@ -0,0 +1,194 @@
+# R3 Node Schema
+
+Verified node shapes for Spring '26 / API v66 orgs.
+
+## load
+
+`mode` valid values: `SYNCED` (default — replicates data before processing), `DIRECT` (queries live, no replication lag but higher API cost), `AUTO` (platform chooses).
+
+```json
+{
+  "action": "load",
+  "sources": [],
+  "parameters": {
+    "dataset": {
+      "type": "connectedDataset",
+      "label": "Opportunity",
+      "connectionName": "SFDC_LOCAL",
+      "sourceObjectName": "Opportunity"
+    },
+    "fields": ["Id", "AccountId", "StageName", "CloseDate", "Amount"],
+    "mode": "SYNCED",
+    "preserveCurrencyFields": [],
+    "sampleDetails": { "type": "TopN", "sortBy": [] }
+  }
+}
+```
+
+## filter
+```json
+{
+  "action": "filter",
+  "sources": ["LOAD_OPPORTUNITY"],
+  "parameters": {
+    "filterExpressions": [
+      { "field": "StageName", "operator": "EQUAL", "operands": ["Closed Won"], "type": "TEXT" }
+    ]
+  }
+}
+```
+
+## join
+```json
+{
+  "action": "join",
+  "sources": ["FILTER_CLOSED_WON", "LOAD_ACCOUNT"],
+  "parameters": {
+    "joinType": "LOOKUP",
+    "leftKeys": ["AccountId"],
+    "rightKeys": ["Id"],
+    "rightQualifier": "Account"
+  }
+}
+```
+Do NOT pass `rightSelectedFields` — it is rejected. After a LOOKUP join, right-side fields are addressable as `<rightQualifier>.<FieldName>` (e.g. `Account.Name`).
+
+**Join keys must be the same type.** `leftKeys` and `rightKeys` are paired by position. Joining an ID to an ID (`Opportunity.AccountId` → `Account.Id`) works. Joining an ID to a TEXT Name, or a NUMBER Amount to a TEXT code, fails at run time with a type-mismatch on the join keys. Do not stringify IDs to "make the types match" — pick the real lookup field.
+
+## formula
+```json
+{
+  "action": "formula",
+  "sources": ["JOIN_ACCOUNT"],
+  "parameters": {
+    "expressionType": "SQL",
+    "fields": [
+      {
+        "name": "TotalAmount",
+        "label": "Total Amount",
+        "type": "NUMBER",
+        "formulaExpression": "Amount"
+      }
+    ]
+  }
+}
+```
+
+### Critical formula rules
+
+- **`expressionType` must be `"SQL"`** — `"FORMULA"` silently drops the `type` field, defaulting output to TEXT.
+- **`type` must be `"NUMBER"`** for numeric output — `"NUMERIC"`, `"DECIMAL"`, `"INTEGER"` etc. normalize to TEXT at write time, causing runtime: *"formula generates decimal(35,17) but output type is TEXT"*.
+- Valid `type` values: `"NUMBER"`, `"TEXT"`, `"DATE"`, `"DATETIME"`.
+- Do NOT include `precision` or `scale` — they trigger *"Unrecognized field 'scale'"*.
+- **Numeric outputs become measures, not dimensions.** SAQL `group q by 'CloseYear'` fails with errorCode 119 if CloseYear is NUMBER. Use `date_format` with `type: "TEXT"` for groupable date dimensions.
+- **One field per formula node — hard UI constraint.** REST API accepts multiple fields and the recipe compiles/runs fine, but the Recipe Designer breaks with *"Can't Load the Recipe — A node can only define one field."* Always chain separate single-field formula nodes:
+  ```json
+  "COMPUTE_YEAR":  { "action": "formula", "sources": ["JOIN_ACCOUNT"],   "parameters": { "expressionType": "SQL", "fields": [{ "name": "CloseYear",  "type": "TEXT", "formulaExpression": "date_format(CloseDate, 'yyyy')" }] } },
+  "COMPUTE_MONTH": { "action": "formula", "sources": ["COMPUTE_YEAR"],    "parameters": { "expressionType": "SQL", "fields": [{ "name": "CloseMonth", "type": "TEXT", "formulaExpression": "date_format(CloseDate, 'MM/yyyy')" }] } }
+  ```
+- **`date_format` patterns**: `'yyyy'` → `"2032"` (TEXT, groupable) ✓ | `'MM/yyyy'` → `"03/2032"` (TEXT, groupable) ✓ | `'MMM yyyy'` → silently produces numeric month integer ✗
+- `lpad()`, `string()`, and bare `concat()` with string-converted date parts are NOT available in Wave recipe SQL — use `date_format`.
+- **`coalesce()` is not reliable in recipe SQL.** Null/blank TEXT dimensions use a `case` expression, one field per node:
+  ```sql
+  case when (Account.Industry is null or Account.Industry = '') then 'Unknown' else Account.Industry end
+  ```
+- **Conditional buckets** also use `case` (not `IFF` / `IF`). Example deal-size TEXT dimension:
+  ```sql
+  case when Amount >= 100000 then 'Large' when Amount >= 50000 then 'Medium' else 'Small' end
+  ```
+- **Quarter as TEXT**: there is no proven `'QQ'` / `'Q'` `date_format` pattern. Derive it from the month string:
+  ```sql
+  case when date_format(CloseDate, 'MM') <= '03' then 'Q1' when date_format(CloseDate, 'MM') <= '06' then 'Q2' when date_format(CloseDate, 'MM') <= '09' then 'Q3' else 'Q4' end
+  ```
+- **Changing formula field `type` requires DELETE + re-POST** — `PATCH ?format=R3` may not update the runtime compiled artifact; multipart PATCH destroys compiled state entirely.
+
+## extractGrains (EXTRACT0)
+```json
+{
+  "action": "extractGrains",
+  "sources": ["COMPUTE_CLOSE_MONTH"],
+  "parameters": { "grainExtractions": [] }
+}
+```
+Always insert EXTRACT0 between the last formula node and aggregate. The aggregate must list `EXTRACT0` in its `sources`, not the last formula node directly.
+
+## aggregate
+```json
+{
+  "action": "aggregate",
+  "sources": ["EXTRACT0"],
+  "parameters": {
+    "aggregations": [
+      { "name": "TotalRevenue", "label": "Total Revenue", "action": "SUM", "source": "TotalAmount" }
+    ],
+    "groupings": ["AccountId", "Account.Name", "CloseYear", "CloseMonth"],
+    "nodeType": "STANDARD",
+    "pivots": []
+  }
+}
+```
+Every column in `groupings` must physically exist on the upstream node's output. Wave does NOT auto-derive `<Date>_Year` / `<Date>_Month` in mid-pipeline — derive them via formula nodes.
+
+## save
+```json
+{
+  "action": "save",
+  "sources": ["AGGREGATE_BY_ACCOUNT_MONTH"],
+  "parameters": {
+    "dataset": {
+      "type": "analyticsDataset",
+      "label": "DTS_OpportunityRev",
+      "name": "DTS_OpportunityRev",
+      "folderName": "OpportunityInsights"
+    },
+    "fields": [],
+    "measuresToCurrencies": []
+  }
+}
+```
+
+## Common errors → fixes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Recipe in `New` status, `targetDataflowId` null | Multipart upload instead of `?format=R3` JSON | Re-create with `POST /wave/recipes?format=R3` |
+| `500 "tableModelInfo is null"` | Multipart PATCH destroyed compiled state | DELETE recipe and re-POST via R3 JSON body |
+| `400 "Recipe Definition JSON is missing"` | Sent multipart while using `?format=R3` | Use plain `application/json` with `recipeDefinition` embedded |
+| Formula type mismatch at runtime | Wrong `type` (e.g. `"TEXT"`) on numeric formula | Use `type: "NUMBER"` and `expressionType: "SQL"` |
+| Aggregate: `Can't find field _Year` | Auto-derived helpers don't exist mid-pipeline | Add formula node: `date_format(CloseDate, 'yyyy')` |
+| `400 errorCode 276` on POST | Recipe name already exists | Use `PATCH /wave/recipes/{id}?format=R3` instead |
+| `400 Id not found: 05v...` on dataflowjobs | Passed recipe id instead of `targetDataflowId` | Use the `02K...` id |
+| Recipe opens with "Can't Load the Recipe" | Formula node has multiple fields | Split into chained single-field formula nodes |
+
+## Common wrong variants
+
+The API silently rejects incorrect field names, function expressions, and structural keys. Use the values in the Correct column verbatim.
+
+| Node type | Correct usage / field name | Common wrong variant |
+|-----------|-------------------|----------------------|
+| load | `parameters.dataset.type: "connectedDataset"` | `connection: "LocalSalesforce"` |
+| load | `parameters.dataset.connectionName: "SFDC_LOCAL"` | `connection` key at top level |
+| load | `parameters.dataset.sourceObjectName: "Opportunity"` | `object` key |
+| filter | `parameters.filterExpressions[].operator: "EQUAL"` | `predicate.expression` |
+| filter | `parameters.filterExpressions[].operands: ["Closed Won"]` | `value` key |
+| join | `parameters.joinType: "LOOKUP"` | `"Left"`, `"INNER"` |
+| join | `parameters.leftKeys: ["AccountId"]` | `leftKey` (singular) |
+| join | `parameters.rightKeys: ["Id"]` | `rightKey` (singular) |
+| join | `parameters.rightQualifier: "Account"` | `rightPrefix` |
+| formula | `action: "formula"` | `"computeExpression"`, `"augmentColumns"`, `"transform"` |
+| formula | `parameters.fields[].formulaExpression` | `formula`, `expression` |
+| formula | `parameters.fields` (array key) | `"columns"` |
+| formula | field names unquoted: `date_format(CloseDate, 'yyyy')` | backtick-quoted: `` date_format(`CloseDate`, 'yyyy') `` |
+| formula | `parameters.fields[].type: "TEXT"` | `dataType` |
+| formula | `date_format(CloseDate, 'yyyy')` | `TO_CHAR(CloseDate, 'YYYY')` |
+| extractGrains | `parameters.grainExtractions: []` | `grainFields: [...]` |
+| aggregate | `parameters.aggregations[].action: "SUM"` | `operation` |
+| aggregate | `parameters.aggregations[].source: "Amount"` | `field` |
+| aggregate | `parameters.groupings: [...]` | `groupBy` |
+| aggregate | `parameters.nodeType: "STANDARD"` | absent |
+| aggregate | `parameters.pivots: []` | absent |
+| save | `parameters.dataset.folderName: "AppName"` | `app`, `folder` |
+| save | `parameters.fields: []` | absent |
+| save | `parameters.measuresToCurrencies: []` | absent |
+| ui connectors | `{ "source": "A", "target": "B" }` | `{ "from": "A", "to": "B" }` |
+| ui containers | `"graph": { ... }` | `"children": { ... }` |

package/skills/crm-analytics-wave-generate/references/scripts-reference.md

@@ -0,0 +1,17 @@
+# Scripts Reference
+
+All scripts accept org alias as the first positional arg and read `accessToken` + `instanceUrl` from `sf org display -o <alias> --json`.
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `scripts/create_app.js` | Idempotently create a CRMA app (folder). Lists existing folders first; only creates if missing. Do NOT include `assetIcon`. | `node scripts/create_app.js <alias> <appName>` |
+| `scripts/deploy_and_run_recipe.js` | Create + compile + run a recipe end-to-end. POSTs or PATCHes via `findExistingRecipe` upsert logic. Polls until terminal. | `node scripts/deploy_and_run_recipe.js <alias> <recipeFile.wdpr> <appName> <recipeName>` |
+| `scripts/probe_recipe.js` | Fetch a recipe with `?format=R3` and print compile status + `targetDataflowId`. | `node scripts/probe_recipe.js <alias> <recipeId>` |
+| `scripts/fetch_dataset_xmd.js` | Look up a dataset by name and dump its current-version XMD (dimensions / measures / dates). Use before generating synthetic data so the schema matches. | `node scripts/fetch_dataset_xmd.js <alias> <datasetName>` |
+| `scripts/gen_synthetic_dataset.js` | Schema-driven synthetic data generator. Reads live XMD, classifies each column by name pattern (`*Id`, `*Industry`, `*Year`, `*Amount`), renames dotted fields to underscored, writes CSV + Wave-compatible `metadata.json`. Default target: `<source>_Synthetic`. | `node scripts/gen_synthetic_dataset.js <alias> <sourceDatasetName>` |
+| `scripts/upload_dataset.js` | Upload a CSV to a new or existing dataset via InsightsExternalData API. Polls until ingestion is terminal. | `node scripts/upload_dataset.js <alias> <csvPath> <metadataJsonPath> <datasetAlias> <folderId>` |
+| `scripts/verify_synthetic_dataset.js` | Post-upload SAQL sanity checks: row count, sum/min/max, edge-case counts, group-by-dimension breakdowns. | `node scripts/verify_synthetic_dataset.js <alias> <datasetId> <versionId>` |
+| `scripts/find_unused_dataset_fields.js` | Given a dataset name, list every XMD field that no dashboard SAQL references. | `node scripts/find_unused_dataset_fields.js <alias> <datasetName>` |
+| `scripts/verify_dashboard_steps.js` | For each step in a deployed dashboard, GET stored SAQL, decode HTML entities, swap dataset name for `id/version`, POST to `/wave/query`. Prints HTTP status + row count per step. Update `DASH_ID` and `DS` constants at the top before running. | `node scripts/verify_dashboard_steps.js <alias>` |
+| `scripts/patch_t_oppo_view.js` | Full-cycle PATCH template: GET state → `decodeAll` every step query → merge dark theme → PATCH. Use as the canonical pattern for future dashboard PATCH scripts. | `node scripts/patch_t_oppo_view.js <alias>` |
+| `scripts/check_connector_error.sh` | GET `/wave/dataConnectors/{id}`, parse `errorCategory`, exit 0 if `System` (safe to retry), exit 1 if `User`/`Limit`/unknown (do not retry — fix config first). | `bash scripts/check_connector_error.sh <alias> <connectorId>` |

package/skills/crm-analytics-wave-generate/references/ui-section-template.md

@@ -0,0 +1,68 @@
+# Designer-Native UI Section
+
+The Recipe Designer detects old-style `ui` sections (old `position: {x,y}` format, empty `connectors: []`, no `type` on nodes) and shows the "Can't Load the Recipe" repair popup on every open. Always use the Designer-native format below.
+
+## Node type mappings
+
+| Recipe node | UI `type` |
+|-------------|-----------|
+| `load` | `LOAD_DATASET` |
+| `filter` | `FILTER` |
+| `join` | `JOIN` |
+| `formula` (all chained) | Grouped inside a `TRANSFORM` UI node |
+| `extractGrains` | Inside the `AGGREGATE` UI node's inner `graph` |
+| `aggregate` | Inside the `AGGREGATE` UI node's inner `graph` |
+| `save` | `OUTPUT` |
+
+## Rules for grouping formula nodes into TRANSFORM
+
+- ALL consecutive formula nodes go into a single `TRANSFORM0` UI node.
+- The inner `graph` lists every formula node name with `{ "parameters": { "type": "BASE_FORMULA_UI" } }`.
+- The inner `connectors` list the formula→formula chain.
+- The outer `connectors` only reference UI node names (TRANSFORM0, AGGREGATE0, etc.), never individual internal formula node names.
+- Always insert `EXTRACT0` (`extractGrains`) inside the AGGREGATE UI node's `graph`. The aggregate node must source from EXTRACT0, not the last formula node.
+
+## Template (filter → join → 2 formula nodes → aggregate → save)
+
+```json
+"ui": {
+  "nodes": {
+    "LOAD_OPPORTUNITY": { "label": "Opportunity", "type": "LOAD_DATASET", "top": 112, "left": 112, "parameters": { "sampleSize": 2000 } },
+    "LOAD_ACCOUNT":     { "label": "Account",     "type": "LOAD_DATASET", "top": 252, "left": 252, "parameters": { "sampleSize": 2000 } },
+    "FILTER_CLOSED_WON": { "label": "FILTER_CLOSED_WON", "type": "FILTER", "top": 112, "left": 252 },
+    "JOIN_ACCOUNT":      { "label": "JOIN_ACCOUNT",      "type": "JOIN",   "top": 112, "left": 392 },
+    "TRANSFORM0": {
+      "label": "TRANSFORM0", "type": "TRANSFORM", "top": 112, "left": 532,
+      "graph": {
+        "COMPUTE_YEAR":  { "parameters": { "type": "BASE_FORMULA_UI" } },
+        "COMPUTE_MONTH": { "parameters": { "type": "BASE_FORMULA_UI" } }
+      },
+      "connectors": [{ "source": "COMPUTE_YEAR", "target": "COMPUTE_MONTH" }]
+    },
+    "AGGREGATE0": {
+      "label": "AGGREGATE0", "type": "AGGREGATE", "top": 112, "left": 672,
+      "graph": { "EXTRACT0": null, "AGGREGATE_NODE": null },
+      "connectors": [{ "source": "EXTRACT0", "target": "AGGREGATE_NODE" }]
+    },
+    "OUTPUT_DATASET": { "label": "OUTPUT_DATASET", "type": "OUTPUT", "top": 112, "left": 812 }
+  },
+  "connectors": [
+    { "source": "LOAD_OPPORTUNITY",  "target": "FILTER_CLOSED_WON" },
+    { "source": "FILTER_CLOSED_WON", "target": "JOIN_ACCOUNT" },
+    { "source": "LOAD_ACCOUNT",      "target": "JOIN_ACCOUNT" },
+    { "source": "JOIN_ACCOUNT",      "target": "TRANSFORM0" },
+    { "source": "TRANSFORM0",        "target": "AGGREGATE0" },
+    { "source": "AGGREGATE0",        "target": "OUTPUT_DATASET" }
+  ],
+  "hiddenColumns": []
+}
+```
+
+Also add at the top level of `recipeDefinition`:
+- `"runMode": "full"`
+
+Add on load nodes: `"mode": "SYNCED"`, `"preserveCurrencyFields": []`, `"sampleDetails": {"type":"TopN","sortBy":[]}`
+
+Add on save node: `"measuresToCurrencies": []`
+
+Add on aggregate node: `"nodeType": "STANDARD"`, `"pivots": []`

package/skills/crm-analytics-wave-generate/scripts/check_connector_error.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# GET /wave/dataConnectors/{id}, parse errorCategory, exit 0 if safe to retry (System), 1 if not (User/Limit/unknown).
+# Usage: bash scripts/check_connector_error.sh <alias> <connectorId>
+# Exit codes: 0 = System error (safe to retry) | 1 = User/Limit/unknown (do not retry, fix config first)
+
+set -euo pipefail
+
+ALIAS="${1:?Usage: check_connector_error.sh <alias> <connectorId>}"
+CONNECTOR_ID="${2:?Usage: check_connector_error.sh <alias> <connectorId>}"
+
+ORG_JSON=$(sf org display -o "$ALIAS" --json 2>/dev/null)
+ACCESS_TOKEN=$(echo "$ORG_JSON" | grep -o '"accessToken": *"[^"]*"' | cut -d'"' -f4)
+INSTANCE_URL=$(echo "$ORG_JSON" | grep -o '"instanceUrl": *"[^"]*"' | cut -d'"' -f4)
+
+if [[ -z "$ACCESS_TOKEN" || -z "$INSTANCE_URL" ]]; then
+  echo '{"error":"Could not retrieve org credentials. Run: sf org display -o <alias>"}' >&2
+  exit 1
+fi
+
+RESPONSE=$(curl -s -f \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  "${INSTANCE_URL}/services/data/v59.0/wave/dataConnectors/${CONNECTOR_ID}")
+
+ERROR_CATEGORY=$(echo "$RESPONSE" | grep -o '"errorCategory":"[^"]*"' | cut -d'"' -f4)
+ERROR_MESSAGE=$(echo "$RESPONSE" | grep -o '"errorMessage":"[^"]*"' | cut -d'"' -f4)
+STATUS=$(echo "$RESPONSE" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
+
+echo "{\"connectorId\":\"$CONNECTOR_ID\",\"status\":\"$STATUS\",\"errorCategory\":\"$ERROR_CATEGORY\",\"errorMessage\":\"$ERROR_MESSAGE\"}"
+
+case "$ERROR_CATEGORY" in
+  System)
+    echo "errorCategory=System: platform-side issue — safe to retry." >&2
+    exit 0
+    ;;
+  User)
+    echo "errorCategory=User: config or credential issue — retry will not fix this. Check connector settings." >&2
+    exit 1
+    ;;
+  Limit)
+    echo "errorCategory=Limit: org quota exceeded — retry will not fix this. Check org limits." >&2
+    exit 1
+    ;;
+  *)
+    # Unknown category — check for generic "contact support" message
+    if echo "$ERROR_MESSAGE" | grep -qi "contact support"; then
+      echo "errorCategory unknown but message contains 'contact support' — treating as System, safe to retry once." >&2
+      exit 0
+    fi
+    echo "errorCategory='$ERROR_CATEGORY' unrecognised — treating as non-retryable." >&2
+    exit 1
+    ;;
+esac

package/skills/crm-analytics-wave-generate/scripts/create_app.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Idempotently create a CRMA app (folder). Lists existing folders first; only creates if missing.
+// Do NOT include assetIcon — it is rejected by the Wave REST API.
+// Usage: node scripts/create_app.js <alias> <appName>
+
+const { execSync, execFileSync } = require("child_process");
+
+function getOrgCredentials(alias) {
+  const result = execFileSync('sf', ['org', 'display', '-o', alias, '--json'], { encoding: "utf8" });
+  const json = JSON.parse(result);
+  return { accessToken: json.result.accessToken, instanceUrl: json.result.instanceUrl };
+}
+
+function apiFetch(instanceUrl, accessToken, path, method = "GET", body = null) {
+  const url = `${instanceUrl}${path}`;
+  const args = [
+    "-s",
+    "-H", `Authorization: Bearer ${accessToken}`,
+    "-H", "Content-Type: application/json",
+    "-X", method,
+    "-w", "\\nHTTP_STATUS:%{http_code}",
+  ];
+  if (body) args.push("-d", JSON.stringify(body));
+  args.push(url);
+  const raw = execSync(`curl ${args.map(a => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ")}`, { encoding: "utf8" });
+  const parts = raw.split("\nHTTP_STATUS:");
+  const httpStatus = parseInt(parts[1] || "0", 10);
+  if (httpStatus < 200 || httpStatus >= 300) {
+    throw new Error(`HTTP ${httpStatus} on ${method} ${path}: ${parts[0]}`);
+  }
+  return JSON.parse(parts[0]);
+}
+
+const [,, alias, appName] = process.argv;
+if (!alias || !appName) {
+  console.error("Usage: node create_app.js <alias> <appName>");
+  process.exit(1);
+}
+
+const { accessToken, instanceUrl } = getOrgCredentials(alias);
+
+// List existing folders
+const listResult = apiFetch(instanceUrl, accessToken, "/services/data/v59.0/wave/folders");
+const folders = listResult.folders || [];
+const existing = folders.find(f => f.name === appName || f.developerName === appName);
+
+if (existing) {
+  console.log(JSON.stringify({ status: "exists", folderId: existing.id, folderName: existing.name }));
+  process.exit(0);
+}
+
+// Create the folder
+const created = apiFetch(instanceUrl, accessToken, "/services/data/v59.0/wave/folders", "POST", {
+  name: appName,
+  developerName: appName,
+  folderType: "Shared",
+});
+
+console.log(JSON.stringify({ status: "created", folderId: created.id, folderName: created.name }));

package/skills/crm-analytics-wave-generate/scripts/deploy_and_run_recipe.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Create + compile + run a Wave Recipe end-to-end via REST API at ?format=R3.
+// POST or PATCH the recipe, assert targetDataflowId is returned, trigger a Run Now, poll until terminal.
+// Usage: node scripts/deploy_and_run_recipe.js <alias> <recipeFile.wdpr> <appName> <recipeName>
+
+const { execSync, execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const TERMINAL_STATUSES = new Set(["Success", "Failure", "Warning", "Cancelled"]);
+const POLL_INTERVAL_MS = 10000;
+const MAX_WAIT_MS = 20 * 60 * 1000;
+
+function getOrgCredentials(alias) {
+  const result = execFileSync('sf', ['org', 'display', '-o', alias, '--json'], { encoding: "utf8" });
+  const json = JSON.parse(result);
+  return { accessToken: json.result.accessToken, instanceUrl: json.result.instanceUrl };
+}
+
+function apiFetch(instanceUrl, accessToken, path, method = "GET", body = null) {
+  const url = `${instanceUrl}${path}`;
+  const args = [
+    "-s",
+    "-H", `Authorization: Bearer ${accessToken}`,
+    "-H", "Content-Type: application/json",
+    "-X", method,
+    "-w", "\\nHTTP_STATUS:%{http_code}",
+  ];
+  if (body !== null) args.push("-d", JSON.stringify(body));
+  args.push(url);
+  const raw = execSync(`curl ${args.map(a => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ")}`, {
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const parts = raw.split("\nHTTP_STATUS:");
+  const httpStatus = parseInt(parts[1] || "0", 10);
+  if (httpStatus < 200 || httpStatus >= 300) {
+    throw new Error(`HTTP ${httpStatus} on ${method} ${path}: ${parts[0]}`);
+  }
+  return JSON.parse(parts[0]);
+}
+
+function sleep(ms) {
+  execSync(`sleep ${ms / 1000}`);
+}
+
+const [,, alias, recipeFile, appName, recipeName] = process.argv;
+if (!alias || !recipeFile || !appName || !recipeName) {
+  console.error("Usage: node deploy_and_run_recipe.js <alias> <recipeFile.wdpr> <appName> <recipeName>");
+  process.exit(1);
+}
+
+const { accessToken, instanceUrl } = getOrgCredentials(alias);
+
+// Read the .wdpr file — it contains only the recipeDefinition object
+const recipeDefinition = JSON.parse(fs.readFileSync(path.resolve(recipeFile), "utf8"));
+
+// Look up folder id
+const folderList = apiFetch(instanceUrl, accessToken, "/services/data/v59.0/wave/folders");
+const folder = (folderList.folders || []).find(f => f.name === appName || f.developerName === appName);
+if (!folder) {
+  console.error(`Folder "${appName}" not found. Run create_app.js first.`);
+  process.exit(1);
+}
+
+// Find existing recipe by name
+const recipeList = apiFetch(instanceUrl, accessToken, "/services/data/v59.0/wave/recipes");
+const existingRecipe = (recipeList.recipes || []).find(r => r.name === recipeName || r.label === recipeName);
+
+let recipe;
+if (existingRecipe) {
+  // PATCH at ?format=R3
+  recipe = apiFetch(instanceUrl, accessToken,
+    `/services/data/v59.0/wave/recipes/${existingRecipe.id}?format=R3`,
+    "PATCH", { recipeDefinition }
+  );
+} else {
+  // POST at ?format=R3
+  recipe = apiFetch(instanceUrl, accessToken,
+    `/services/data/v59.0/wave/recipes?format=R3`,
+    "POST", {
+      recipeDefinition,
+      name: recipeName,
+      label: recipeName,
+      folder: { id: folder.id },
+    }
+  );
+}
+
+const targetDataflowId = recipe.targetDataflowId;
+if (!targetDataflowId) {
+  console.error("targetDataflowId is null — recipe did not compile. Check recipeDefinition structure.");
+  console.error(JSON.stringify(recipe, null, 2));
+  process.exit(1);
+}
+
+console.log(`Recipe id: ${recipe.id}, targetDataflowId: ${targetDataflowId}`);
+
+// Trigger Run Now
+const job = apiFetch(instanceUrl, accessToken, "/services/data/v59.0/wave/dataflowjobs", "POST", {
+  dataflowId: targetDataflowId,
+  command: "start",
+});
+
+const jobId = job.id;
+console.log(`Dataflow job started: ${jobId}`);
+
+// Poll until terminal
+const deadline = Date.now() + MAX_WAIT_MS;
+while (Date.now() < deadline) {
+  sleep(POLL_INTERVAL_MS);
+  const jobStatus = apiFetch(instanceUrl, accessToken, `/services/data/v59.0/wave/dataflowjobs/${jobId}`);
+  const status = jobStatus.status;
+  console.log(`Job status: ${status}`);
+  if (TERMINAL_STATUSES.has(status)) {
+    console.log(JSON.stringify({ jobId, status, recipeId: recipe.id, targetDataflowId }));
+    process.exit(status === "Success" || status === "Warning" ? 0 : 1);
+  }
+}
+
+console.error("Timed out waiting for job to complete.");
+process.exit(1);

package/skills/crm-analytics-wave-generate/scripts/fetch_dataset_xmd.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Look up a dataset by name and dump its current-version XMD (dimensions / measures / dates).
+// Use before generating synthetic data so the schema matches the live dataset.
+// Usage: node scripts/fetch_dataset_xmd.js <alias> <datasetName>
+
+const { execSync, execFileSync } = require("child_process");
+
+function getOrgCredentials(alias) {
+  const result = execFileSync('sf', ['org', 'display', '-o', alias, '--json'], { encoding: "utf8" });
+  const json = JSON.parse(result);
+  return { accessToken: json.result.accessToken, instanceUrl: json.result.instanceUrl };
+}
+
+function apiFetch(instanceUrl, accessToken, path) {
+  const url = `${instanceUrl}${path}`;
+  const args = [
+    "-s",
+    "-H", `Authorization: Bearer ${accessToken}`,
+    "-w", "\\nHTTP_STATUS:%{http_code}",
+    url,
+  ];
+  const raw = execSync(`curl ${args.map(a => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ")}`, {
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const parts = raw.split("\nHTTP_STATUS:");
+  const httpStatus = parseInt(parts[1] || "0", 10);
+  if (httpStatus < 200 || httpStatus >= 300) {
+    throw new Error(`HTTP ${httpStatus} on GET ${path}: ${parts[0]}`);
+  }
+  return JSON.parse(parts[0]);
+}
+
+const [,, alias, datasetName] = process.argv;
+if (!alias || !datasetName) {
+  console.error("Usage: node fetch_dataset_xmd.js <alias> <datasetName>");
+  process.exit(1);
+}
+
+const { accessToken, instanceUrl } = getOrgCredentials(alias);
+
+// Find the dataset by name
+const datasets = apiFetch(instanceUrl, accessToken, `/services/data/v59.0/wave/datasets`);
+const dataset = (datasets.datasets || []).find(d => d.name === datasetName || d.developerName === datasetName);
+if (!dataset) {
+  console.error(`Dataset "${datasetName}" not found.`);
+  process.exit(1);
+}
+
+// Fetch XMD for the current version
+const versionId = dataset.currentVersionId;
+const xmd = apiFetch(instanceUrl, accessToken, `/services/data/v59.0/wave/datasets/${dataset.id}/versions/${versionId}/xmd`);
+
+console.log(JSON.stringify({
+  datasetId: dataset.id,
+  datasetName: dataset.name,
+  versionId,
+  xmd,
+}, null, 2));