@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/consumer-goods-accruals-datakit-deploy/scripts/setup.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { getOrgDetails, getOrgNamespace } = require('./steps/utils');
+
+// Import all step modules
+const checkPrerequisites = require('./steps/00-check-prerequisites');
+const downloadStaticResource = require('./steps/01-download-static-resource');
+const replaceOrgId = require('./steps/02-replace-org-id');
+const deployMetadata = require('./steps/03-deploy-metadata');
+const deployEngine = require('./steps/04-deploy-engine');
+const deployTPMAccruals = require('./steps/05-deploy-tpm-accruals');
+const createDataSpace = require('./steps/06-create-dataspace');
+const deployAccrualsReports = require('./steps/07-deploy-accruals-reports');
+const deployUI = require('./steps/08-deploy-ui');
+const completion = require('./steps/09-completion');
+
+/**
+ * Parse command line arguments
+ * Supports both flags (--flag=value, --flag value, -f value) and positional arguments
+ * @returns {{ orgAlias: string|null, skipDataSpace: boolean, salesOrg: string, dryRun: boolean, namespace: string|null }}
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {
+    orgAlias: null,
+    skipDataSpace: false,
+    salesOrg: null,
+    dryRun: false,
+    namespace: null,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    // Handle --flag=value format
+    if (arg.includes('=')) {
+      const [key, value] = arg.split('=');
+      switch (key) {
+        case '--org':
+        case '-o':
+          result.orgAlias = value;
+          break;
+        case '--sales-org':
+        case '-s':
+          result.salesOrg = value;
+          break;
+        case '--skip-dataspace':
+          result.skipDataSpace = value === 'true';
+          break;
+        case '--dry-run':
+          result.dryRun = value === 'true';
+          break;
+        case '--namespace':
+        case '-n':
+          result.namespace = value;
+          break;
+      }
+      continue;
+    }
+
+    // Handle --flag value format and boolean flags
+    switch (arg) {
+      case '--org':
+      case '-o':
+        result.orgAlias = args[++i];
+        break;
+      case '--sales-org':
+      case '-s':
+        result.salesOrg = args[++i];
+        break;
+      case '--skip-dataspace':
+        result.skipDataSpace = true;
+        break;
+      case '--dry-run':
+      case '-d':
+        result.dryRun = true;
+        break;
+      case '--namespace':
+      case '-n':
+        result.namespace = args[++i];
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        // Positional argument (org alias for backward compatibility)
+        if (!arg.startsWith('-') && !result.orgAlias) {
+          result.orgAlias = arg;
+        }
+        break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Print help message
+ */
+function printHelp() {
+  console.log(`
+Usage: node setup.js [options] [org-alias]
+
+Options:
+  -o, --org <alias>       Salesforce org alias (can also use SF_ORG_ALIAS env var)
+  -s, --sales-org <org>   Sales org identifier (required; can also use SALES_ORG env var)
+  -n, --namespace <ns>    Org namespace prefix WITHOUT trailing "__" (e.g. "cgcloud_dev").
+                          If omitted, the namespace is auto-detected from the org.
+                          Use empty string ("") to force unmanaged behavior.
+      --skip-dataspace    Skip Data Space creation (can also use SKIP_DATASPACE=true env var)
+  -d, --dry-run           Show what would be done without making any changes
+  -h, --help              Show this help message
+
+Examples:
+  node setup.js --org my-org --sales-org 0001
+  node setup.js --org my-org --sales-org 0002
+  node setup.js -o my-org -s 0002 --skip-dataspace
+  node setup.js --dry-run --org my-org --sales-org 0001
+  node setup.js --org my-org --namespace cgcloud_dev
+
+Environment variables:
+  SF_ORG_ALIAS      Salesforce org alias
+  SALES_ORG         Sales org identifier (required)
+  SKIP_DATASPACE    Set to "true" to skip Data Space creation
+  DRY_RUN           Set to "true" for dry run mode
+  ORG_NAMESPACE     Org namespace prefix WITHOUT trailing "__" (overrides auto-detection)
+`);
+}
+
+/**
+ * Get configuration from CLI args and environment variables
+ * CLI args take precedence over environment variables
+ * @returns {{ orgAlias: string, skipDataSpace: boolean, salesOrg: string, dryRun: boolean, namespaceOverride: string|null }}
+ */
+function getConfig() {
+  const cliArgs = parseArgs();
+
+  // CLI args take precedence over environment variables
+  const orgAlias = cliArgs.orgAlias || process.env.SF_ORG_ALIAS;
+  const skipDataSpace = cliArgs.skipDataSpace || process.env.SKIP_DATASPACE === 'true';
+  const salesOrg = cliArgs.salesOrg || process.env.SALES_ORG || null;
+  const dryRun = cliArgs.dryRun || process.env.DRY_RUN === 'true';
+
+  // namespaceOverride is null when neither CLI nor env was provided (=> auto-detect),
+  // or a string (possibly empty) when the user explicitly specified one.
+  let namespaceOverride = null;
+  if (cliArgs.namespace !== null && cliArgs.namespace !== undefined) {
+    namespaceOverride = cliArgs.namespace;
+  } else if (process.env.ORG_NAMESPACE !== undefined) {
+    namespaceOverride = process.env.ORG_NAMESPACE;
+  }
+
+  if (!orgAlias) {
+    console.error('Error: Org alias not provided.');
+    console.error('Usage: node setup.js <org-alias>');
+    console.error('   OR: node setup.js --org <org-alias>');
+    console.error('   OR: SF_ORG_ALIAS=<org-alias> node setup.js');
+    console.error('\nRun "node setup.js --help" for more options.');
+    process.exit(1);
+  }
+
+  if (!salesOrg) {
+    console.error('Error: Sales org not provided.');
+    console.error('Usage: node setup.js --sales-org <value>');
+    console.error('   OR: SALES_ORG=<value> node setup.js');
+    console.error('\nRun "node setup.js --help" for available options.');
+    process.exit(1);
+  }
+
+  return { orgAlias, skipDataSpace, salesOrg, dryRun, namespaceOverride };
+}
+
+/**
+ * Validate salesOrg and namespaceOverride inputs.
+ * Exits the process with an error message if validation fails.
+ * @param {string} salesOrg - Must be exactly 4 alphanumeric characters.
+ * @param {string|null} namespaceOverride - When non-null, must be 1-15 alphanumeric characters.
+ */
+function validateInputs(salesOrg, namespaceOverride, orgAlias) {
+  // Org alias: Salesforce allows alphanumeric, hyphens, underscores, dots, and @ (usernames).
+  // Restrict to safe characters to prevent shell metacharacter injection on Windows cmd.exe.
+  // Allow alphanumeric, hyphens, underscores, dots, @, and + (valid in Salesforce usernames, e.g. user+ci@example.com).
+  // None of these characters are cmd.exe metacharacters, so shell injection via org alias is prevented.
+  if (!/^[A-Za-z0-9_\-@.+]+$/.test(orgAlias)) {
+    console.error(`Error: Invalid org alias "${orgAlias}". Must contain only alphanumeric characters, hyphens, underscores, dots, @, or +.`);
+    process.exit(1);
+  }
+
+  if (!/^[A-Za-z0-9]{4}$/.test(salesOrg)) {
+    console.error('Error: Invalid sales org.');
+    process.exit(1);
+  }
+
+  if (namespaceOverride !== null && namespaceOverride !== '' && !/^[A-Za-z0-9]{1,15}$/.test(namespaceOverride)) {
+    console.error('Error: Invalid namespace.');
+    process.exit(1);
+  }
+}
+
+/**
+ * Format a namespace value into the prefix form used in metadata
+ * (i.e. always ends with "__", or is the empty string).
+ */
+function formatNamespace(value) {
+  if (!value) return '';
+  return value.endsWith('__') ? value : `${value}__`;
+}
+
+/**
+ * Derive Data Space name and prefix from sales org
+ * @param {string} salesOrg - The sales org value
+ * @returns {{ dataSpaceName: string, dataSpacePrefix: string }}
+ */
+function getDataSpaceConfig(salesOrg) {
+  const lastChar = salesOrg.slice(-1);
+  return {
+    dataSpaceName: `DataSpace_${salesOrg}`,
+    dataSpacePrefix: `DS${lastChar}_`,
+  };
+}
+
+/**
+ * Main setup function
+ */
+async function main() {
+  console.log('=== Salesforce Org Setup ===\n');
+
+  const config = getConfig();
+  const { orgAlias, skipDataSpace, salesOrg, dryRun, namespaceOverride } = config;
+
+  // Validate inputs before any org access or step execution
+  validateInputs(salesOrg, namespaceOverride, orgAlias);
+
+  const { dataSpaceName, dataSpacePrefix } = getDataSpaceConfig(salesOrg);
+
+  if (dryRun) {
+    console.log('+============================================================================+');
+    console.log('|                              DRY RUN MODE                                  |');
+    console.log('|  All read-only steps will execute. Deployments to org will be skipped.    |');
+    console.log('|  Temp directories will be preserved for inspection.                       |');
+    console.log('+============================================================================+\n');
+  }
+
+  console.log(`Target org: ${orgAlias}`);
+
+  // Verify org is accessible and get org details
+  console.log('Verifying org connection...');
+  let orgId;
+  try {
+    const orgDetails = getOrgDetails(orgAlias);
+    orgId = orgDetails.orgId;
+    console.log(`[OK] Org connection verified (Org ID: ${orgId})\n`);
+  } catch (error) {
+    console.error(`Error: Cannot connect to org "${orgAlias}"`);
+    console.error('Make sure you are logged in via: sf org login web');
+    process.exit(1);
+  }
+
+  // Resolve org namespace: CLI/env override wins; otherwise query the org.
+  // This is needed because component names in DataKitDeploymentLog and field
+  // references in the Accruals Reports payload can carry a namespace prefix
+  // depending on the org (e.g. "cgcloud_dev__" in this repo's dev org).
+  let namespace;
+  if (namespaceOverride !== null && namespaceOverride !== undefined) {
+    namespace = formatNamespace(namespaceOverride);
+    console.log(`Using namespace override: "${namespace || '(none)'}"`);
+  } else {
+    console.log('Detecting org namespace...');
+    namespace = getOrgNamespace(orgAlias);
+    console.log(`Detected namespace: "${namespace || '(none)'}"`);
+  }
+
+  const setupDir = __dirname;
+
+  console.log(`Sales Org: ${salesOrg}`);
+  if (!skipDataSpace) {
+    console.log(`Data Space Name: ${dataSpaceName}`);
+    console.log(`Data Space Prefix: ${dataSpacePrefix}\n`);
+  }
+
+  // Step 0: Check Prerequisites (skip in dry run)
+  if (!dryRun) {
+    await checkPrerequisites();
+  } else {
+    console.log('\n=== Step 0: Check Prerequisites (skipped in dry run) ===\n');
+  }
+
+  // Run all steps in order
+  // Step 1 returns the extraction dir; derive dataKitPath and scriptsDir from it.
+  const cgcloudAddonsDir = await downloadStaticResource(orgAlias, setupDir);
+  const dataKitPath = path.join(cgcloudAddonsDir, 'TPM', 'Accruals', 'TPM Accruals Data Kit');
+  const scriptsDir = path.join(cgcloudAddonsDir, 'TPM', 'Accruals', 'Accruals Data Kit Deployment Scripts');
+  await replaceOrgId(orgId, dataKitPath);
+  await deployMetadata(orgAlias, dataKitPath, dryRun);
+  await deployEngine(orgAlias, scriptsDir, orgId, namespace, dryRun);
+  await deployTPMAccruals(orgAlias, scriptsDir, dataKitPath, orgId, namespace, dryRun);
+
+  // Step 6: Create Data Space (only if Data Spaces are available)
+  if (!skipDataSpace) {
+    await createDataSpace(orgAlias, salesOrg, dataSpaceName, dataSpacePrefix, dryRun);
+  } else {
+    console.log('\n=== Step 6: Skipping Data Space creation (--skip-dataspace) ===\n');
+  }
+
+  // Step 7: Deploy Accruals Reports with Data Space replacements
+  await deployAccrualsReports(orgAlias, cgcloudAddonsDir, skipDataSpace, dataSpaceName, dataSpacePrefix, namespace, dryRun);
+
+  // Step 8: Deploy UI components (TPMAccrualTacticSummary)
+  await deployUI(orgAlias, cgcloudAddonsDir, skipDataSpace, dataSpaceName, dataSpacePrefix, salesOrg, namespace, dryRun);
+
+  // Step 9: Completion and next steps
+  await completion(dryRun);
+
+  console.log('=== Setup completed successfully ===');
+}
+
+// Run the script
+main().catch(error => {
+  console.error('Unexpected error:', error);
+  process.exit(1);
+});

package/skills/consumer-goods-accruals-datakit-deploy/scripts/steps/00-check-prerequisites.js

@@ -0,0 +1,63 @@
+const readline = require('readline');
+
+/**
+ * Step 0: Check Prerequisites
+ * Presents prerequisites to the user and waits for confirmation
+ */
+async function checkPrerequisites() {
+  console.log('\n=== Step 0: Prerequisites ===');
+
+  console.log('\nBefore proceeding, confirm ALL of the following are complete in your org.\n');
+
+  console.log('--- PERMISSIONS ---');
+  console.log('\n1. Assign permission set "Data Cloud Architect" to:');
+  console.log('   - The System Admin user');
+  console.log('   - The user assigned to the Accrual Ingestion Process');
+  console.log('\n2. Enable CRM Analytics (if you need Accruals dashboards):');
+  console.log('   Setup > Feature Settings > Analytics > Analytics > Getting Started > Enable CRM Analytics');
+  console.log('   Then assign permission set "CRM Analytics Plus Admin" to the System Admin.');
+
+  console.log('\n--- DATA CLOUD ---');
+  console.log('\n3. Data Cloud is enabled and set up (via the Data Cloud app, not Setup).');
+  console.log('\n4. Salesforce CRM connector is active:');
+  console.log('   Data Cloud app > Data Cloud Setup > Salesforce CRM > enable Home Org connection.');
+  console.log('   Also activate any other required connectors using the dropdown button.');
+  console.log('\n5. A user is assigned to the Accrual Ingestion Process:');
+  console.log('   Setup > Processing Services Pairing > Accrual Ingestion Process.');
+
+  console.log('\n--- INTEGRATION ---');
+  console.log('\n6. OAuth scope "cdp_ingest_api" is configured on the integration app used by TPM Offcore.');
+  console.log('   Check Setup > App Manager (Connected Apps) or Setup > External Client Apps.');
+  console.log('   The app name varies by org — locate the one used by TPM Offcore.');
+
+  console.log('\n');
+
+  // Wait for user confirmation
+  await waitForUserConfirmation();
+
+  console.log('[OK] Prerequisites confirmed. Proceeding to next step...\n');
+}
+
+/**
+ * Wait for user to press Enter.
+ * Auto-confirms immediately when stdin is not a TTY (piped / headless run).
+ */
+function waitForUserConfirmation() {
+  if (!process.stdin.isTTY) {
+    console.log('[Auto-confirmed: running non-interactively]');
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+
+    rl.question('Press Enter when you have confirmed all prerequisites are met...', () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+module.exports = checkPrerequisites;

package/skills/consumer-goods-accruals-datakit-deploy/scripts/steps/01-download-static-resource.js

@@ -0,0 +1,100 @@
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { execSfJson, getOrgDetails } = require('./utils');
+
+/**
+ * Step 1: Download and extract the CGCloudAddons static resource
+ */
+async function downloadStaticResource(orgAlias, setupDir) {
+  console.log('\n=== Step 1: Downloading CGCloudAddons static resource ===');
+
+  const staticResourceName = 'CGCloudAddons';
+  // Extract to os.tmpdir() to avoid EBUSY locks in the script tree on Windows
+  const extractBase = path.join(os.tmpdir(), `tpm_accruals_extract_${Date.now()}`);
+
+  // Get org details for REST API call
+  console.log('Getting org connection details...');
+  const orgDetails = getOrgDetails(orgAlias);
+
+  // Query for the static resource
+  console.log(`Looking up ${staticResourceName} in org...`);
+  const queryResult = execSfJson(['data', 'query', '--query', `SELECT Id, Name FROM StaticResource WHERE Name = '${staticResourceName}'`, '--target-org', orgAlias, '--json']);
+
+  if (queryResult.status !== 0 || !queryResult.result.records || queryResult.result.records.length === 0) {
+    console.error(`Error: Static resource ${staticResourceName} not found in org`);
+    process.exit(1);
+  }
+
+  const staticResourceId = queryResult.result.records[0].Id;
+  console.log(`Found ${staticResourceName} (ID: ${staticResourceId})`);
+
+  // Download the static resource body using REST API
+  console.log('Downloading static resource content...');
+  fs.mkdirSync(extractBase, { recursive: true });
+  const targetFile = path.join(extractBase, `${staticResourceName}.zip`);
+  const bodyUrl = `${orgDetails.instanceUrl}/services/data/v${orgDetails.apiVersion}/sobjects/StaticResource/${staticResourceId}/Body`;
+
+  await new Promise((resolve, reject) => {
+    const url = new URL(bodyUrl);
+    const req = https.get({
+      hostname: url.hostname,
+      path: url.pathname + url.search,
+      headers: { Authorization: `Bearer ${orgDetails.accessToken}` }
+    }, res => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode} downloading static resource`));
+        res.resume();
+        return;
+      }
+      const out = fs.createWriteStream(targetFile);
+      res.pipe(out);
+      out.on('finish', resolve);
+      out.on('error', reject);
+    });
+    req.on('error', reject);
+  });
+
+  if (!fs.existsSync(targetFile)) {
+    console.error('Error: Failed to download static resource');
+    process.exit(1);
+  }
+
+  console.log(`Static resource saved to: ${targetFile}`);
+
+  // Extract the zip file
+  console.log('Extracting static resource...');
+  const extractDir = path.join(extractBase, staticResourceName);
+  fs.mkdirSync(extractDir, { recursive: true });
+
+  // Extract: use Windows System32 bsdtar on Windows (Git Bash's GNU tar cannot
+  // read ZIP and misinterprets Windows drive letters as URLs). Convert paths to
+  // forward-slash POSIX form so bsdtar receives them correctly.
+  function toPosix(p) { return p.replace(/\\/g, '/'); }
+  const [unzipCmd, unzipArgs] = process.platform === 'win32'
+    ? ['C:\\Windows\\System32\\tar.exe', ['-xf', toPosix(targetFile), '-C', toPosix(extractDir)]]
+    : ['unzip', ['-o', '-q', targetFile, '-d', extractDir]];
+  try {
+    execFileSync(unzipCmd, unzipArgs, { stdio: 'pipe' });
+    console.log(`Extracted to: ${extractDir}`);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.error(
+        `Error: "${unzipCmd}" is not installed or not on PATH — ` +
+        (process.platform === 'win32'
+          ? 'expected the tar.exe bundled with Windows 10 (1803+) / 11'
+          : 'install it (e.g. `apt install unzip`) and retry')
+      );
+    } else {
+      console.error(`Error: Failed to extract zip file — ${error.message}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('[OK] CGCloudAddons static resource downloaded and extracted successfully\n');
+  return extractDir;
+}
+
+module.exports = downloadStaticResource;

package/skills/consumer-goods-accruals-datakit-deploy/scripts/steps/02-replace-org-id.js

@@ -0,0 +1,46 @@
+const fs = require('fs');
+const path = require('path');
+
+function walkFiles(dir, extensions) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) results.push(...walkFiles(full, extensions));
+    else if (extensions.some(ext => entry.name.endsWith(ext))) results.push(full);
+  }
+  return results;
+}
+
+/**
+ * Step 2: Replace __SF_ORG_ID__ placeholder with actual org ID in all metadata files
+ */
+async function replaceOrgId(orgId, dataKitPath) {
+  console.log('\n=== Step 2: Replacing org ID placeholders ===');
+  console.log(`Target directory: ${dataKitPath}`);
+  console.log(`Org ID: ${orgId} (truncated to 15 chars: ${orgId.slice(0, 15)})`);
+
+  // Truncate org ID to 15 characters
+  const truncatedOrgId = orgId.slice(0, 15);
+
+  // Find all XML and JSON files
+  const files = walkFiles(dataKitPath, ['.xml', '.json']);
+
+  let replacementCount = 0;
+
+  files.forEach(file => {
+    try {
+      const content = fs.readFileSync(file, 'utf8');
+      if (content.includes('__SF_ORG_ID__')) {
+        const newContent = content.replace(/__SF_ORG_ID__/g, truncatedOrgId);
+        fs.writeFileSync(file, newContent, 'utf8');
+        replacementCount++;
+      }
+    } catch (error) {
+      console.error(`Warning: Failed to process file ${file}: ${error.message}`);
+    }
+  });
+
+  console.log(`[OK] Replaced org ID placeholder in ${replacementCount} file(s)\n`);
+}
+
+module.exports = replaceOrgId;

package/skills/consumer-goods-accruals-datakit-deploy/scripts/steps/03-deploy-metadata.js

@@ -0,0 +1,46 @@
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const { exec, execDeployJson, execSfJson } = require('./utils');
+
+/**
+ * Step 3: Deploy TPM Accruals Data Kit metadata to the org
+ * @param {string} orgAlias - The Salesforce org alias
+ * @param {string} dataKitPath - Path to the data kit
+ * @param {boolean} dryRun - If true, skip actual deployment
+ */
+async function deployMetadata(orgAlias, dataKitPath, dryRun = false) {
+  console.log('\n=== Step 3: Deploying TPM Accruals Data Kit ===');
+  console.log(`Source: ${dataKitPath}`);
+  console.log(`Target org: ${orgAlias}`);
+
+  if (dryRun) {
+    console.log('[DRY RUN] Skipping deployment - files prepared at:');
+    console.log(`  ${dataKitPath}/force-app`);
+    console.log('[OK] Step 3 completed (dry run)\n');
+    return;
+  }
+
+  // Convert to MDAPI format first, then deploy via --metadata-dir.
+  // This bypasses SF CLI source-tracking ("NothingToDeploy" errors on non-scratch
+  // orgs where tracking state diverges from org reality).
+  const mdapiOut = path.join(os.tmpdir(), `tpm_accruals_mdapi_${Date.now()}`);
+  console.log('Converting source to MDAPI format...');
+  const convertResult = execSfJson(['project', 'convert', 'source', '--output-dir', mdapiOut, '--json'], { cwd: dataKitPath });
+  if (convertResult.status !== 0) {
+    throw new Error(`Source conversion failed: ${convertResult.message || JSON.stringify(convertResult)}`);
+  }
+  console.log(`Converted to: ${convertResult.result && convertResult.result.location || mdapiOut}`);
+
+  console.log('Deploying metadata...');
+  execDeployJson(['project', 'deploy', 'start', '--metadata-dir', mdapiOut, '--target-org', orgAlias]);
+
+  // Clean up temp dir
+  try { fs.rmSync(mdapiOut, { recursive: true }); } catch (cleanupErr) {
+    console.warn(`[WARN] Could not remove temp directory ${mdapiOut}: ${cleanupErr.message}`);
+  }
+
+  console.log('[OK] TPM Accruals Data Kit deployed successfully\n');
+}
+
+module.exports = deployMetadata;