@salesforce/afv-skills 1.44.0 → 1.45.0

package/skills/consumer-goods-tpe-dashboard-custom-kpi-configure/scripts/sf-rest.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Authenticated Salesforce REST callout, replacing `sf api request rest`
+ * everywhere in this skill — that command is beta, doesn't support --json,
+ * and beta CLI surfaces can change or be pulled without notice. Fetches the
+ * org's instanceUrl and access token via the `sf` CLI, then performs a
+ * plain HTTP request with Node's built-in fetch. Access token retrieval is
+ * version-gated the same way as `datakit-for-tpe`'s
+ * `download-static-resource.js`: `sf org auth show-access-token` for CLI
+ * >= 2.136.8 (below that version, `sf org display`'s own `result.accessToken`
+ * is a redacted hint string, not a real token — see the `sfJson`/`getAccessToken`
+ * pair below). The token is never printed.
+ *
+ * CLI usage:
+ *   node sf-rest.js --target-org <username> --path <path> \
+ *     [--method GET|POST|PATCH|DELETE] [--body <json-string>]
+ *
+ * <path> is relative to the org's instanceUrl, e.g.
+ * "/services/apexrest/tpm-api/..." or "/services/data/v63.0/...".
+ * Prints the response body as one line of JSON to stdout on both success
+ * and failure, so a non-2xx error body (e.g. `{"error":"..."}`) is still
+ * readable by the caller. Exit codes: 0 = 2xx response, 1 = non-2xx
+ * response, 2 = usage/CLI error.
+ *
+ * Module usage (for sibling scripts in this same skill's scripts/ dir —
+ * never imported across skill directories):
+ *   const { restRequest } = require('./sf-rest');
+ *   const { ok, status, body } = await restRequest({ targetOrg, path, method, body: jsonString });
+ */
+
+/**
+ * Also exposes two subcommands that print only safe, non-secret fields from
+ * `sf org display --json` — that command's `result` includes `accessToken`
+ * (a live credential), so nothing in this skill should run it directly and
+ * surface the raw output; these strip it before printing:
+ *   node sf-rest.js org-status --target-org <username>
+ *     -> {"username","alias","connectedStatus","orgId"} ; exit 1 if not Connected
+ */
+
+const { execFileSync } = require('child_process');
+
+function sfJson(cliArgs) {
+  // A color-forcing terminal (e.g. Warp's FORCE_COLOR=3) makes `sf` emit ANSI
+  // codes even with --json, which breaks JSON.parse — force color off for
+  // this invocation regardless of the calling shell's env.
+  const raw = execFileSync('sf', cliArgs, {
+    encoding: 'utf8',
+    env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+  });
+  return JSON.parse(raw).result;
+}
+
+const ACCESS_TOKEN_VIA_SHOW_COMMAND_SINCE = [2, 136, 8];
+
+function getCliVersion() {
+  // Unlike every other `sf ... --json` command, `sf version --json` returns
+  // its fields at the top level — no `{status, result}` envelope.
+  const raw = execFileSync('sf', ['version', '--json'], {
+    encoding: 'utf8',
+    env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+  });
+  const { cliVersion } = JSON.parse(raw);
+  const match = cliVersion.match(/(\d+)\.(\d+)\.(\d+)/);
+  // A pre-release/suffixed version string (e.g. a nightly build) that
+  // doesn't match this pattern is treated as "new enough" below, via
+  // isAtLeast's null passthrough — never silently fall back to the
+  // redacted-token path on an unparseable version.
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function isAtLeast(version, minVersion) {
+  if (!version) return true;
+  for (let i = 0; i < minVersion.length; i += 1) {
+    const a = version[i] || 0;
+    const b = minVersion[i] || 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}
+
+function getAccessToken(targetOrg) {
+  const useShowAccessTokenCommand = isAtLeast(
+    getCliVersion(),
+    ACCESS_TOKEN_VIA_SHOW_COMMAND_SINCE
+  );
+  if (useShowAccessTokenCommand) {
+    return sfJson([
+      'org', 'auth', 'show-access-token',
+      '--target-org', targetOrg,
+      '--no-prompt', '--json',
+    ]).accessToken;
+  }
+  return sfJson(['org', 'display', '--target-org', targetOrg, '--json']).accessToken;
+}
+
+// instanceUrl/accessToken don't change within a single script run — caching
+// them per targetOrg avoids 3 fresh `sf` CLI subprocess spawns (org display,
+// version, show-access-token) on every single REST call, which otherwise
+// dominates runtime once a script makes dozens of calls (e.g. cloning every
+// KPI-bound visualization on a dashboard).
+const orgConnectionCache = new Map();
+
+function getOrgConnection(targetOrg) {
+  if (!orgConnectionCache.has(targetOrg)) {
+    const { instanceUrl } = sfJson(['org', 'display', '--target-org', targetOrg, '--json']);
+    const accessToken = getAccessToken(targetOrg);
+    orgConnectionCache.set(targetOrg, { instanceUrl, accessToken });
+  }
+  return orgConnectionCache.get(targetOrg);
+}
+
+async function restRequest({ targetOrg, path, method, body }) {
+  const { instanceUrl, accessToken } = getOrgConnection(targetOrg);
+
+  const headers = { Authorization: `Bearer ${accessToken}` };
+  if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+  const response = await fetch(`${instanceUrl}${path}`, {
+    method: method || 'GET',
+    headers,
+    body,
+  });
+  const text = await response.text();
+  let parsedBody = {};
+  if (text.length) {
+    try {
+      parsedBody = JSON.parse(text);
+    } catch {
+      parsedBody = text;
+    }
+  }
+  return { ok: response.ok, status: response.status, body: parsedBody };
+}
+
+function getOrgStatus(targetOrg) {
+  const info = sfJson(['org', 'display', '--target-org', targetOrg, '--json']);
+  return {
+    username: info.username,
+    alias: info.alias || null,
+    connectedStatus: info.connectedStatus,
+    orgId: info.id,
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    args[token.slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function requireArg(args, name) {
+  if (!args[name]) {
+    console.error(`Missing required --${name}`);
+    process.exit(2);
+  }
+  return args[name];
+}
+
+async function main() {
+  const [maybeCommand, ...rest] = process.argv.slice(2);
+
+  if (maybeCommand === 'org-status') {
+    const args = parseArgs(rest);
+    const status = getOrgStatus(requireArg(args, 'target-org'));
+    process.stdout.write(JSON.stringify(status));
+    if (status.connectedStatus !== 'Connected') process.exit(1);
+    return;
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  const targetOrg = requireArg(args, 'target-org');
+  const path = requireArg(args, 'path');
+  const method = args.method || 'GET';
+
+  const { ok, status, body } = await restRequest({ targetOrg, path, method, body: args.body });
+  process.stdout.write(JSON.stringify(body));
+  if (!ok) {
+    console.error(`sf-rest: HTTP ${status}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+module.exports = { restRequest, getOrgStatus };

package/skills/consumer-goods-tpe-datakit-deploy/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: consumer-goods-tpe-datakit-deploy
+description: "Deploy the TPM Accruals Data Kit components specifically required for Trade Promotion Effectiveness (TPE) dashboards. Use when a customer or admin wants to install or deploy the TPM data kit for TPE dashboards, or as a delegated step from consumer-goods-tpe-dashboard-configure. Do not use this skill if the customer wants to deploy the TPM Accruals Data Kit for the Accruals feature."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  domains: ["Consumer Goods"]
+  relatedSkills:
+    - "consumer-goods-tpe-dashboard-configure"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=20.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# TPE Data Kit Deploy
+
+Deploys the TPM Accruals Data Kit and its DMO mappings into a Salesforce org. Standalone and self-contained — runs on its own, or as a delegated step invoked by `consumer-goods-tpe-dashboard-configure` (Step 7), which passes through its own already-collected username and dry-run flag rather than this skill re-deriving them.
+
+## Inputs to collect first
+
+Ask before starting, unless already supplied by a calling skill. Do not guess.
+
+1. **TPM System Admin username** — already authenticated via `sf` CLI. Verify via the sibling
+   script, never `sf org display --json` directly — that command's raw output includes
+   `accessToken` (a live credential), which this script strips before printing:
+   ```bash
+   node ./scripts/sf-rest.js org-status --target-org <username>
+   ```
+   Prints `{"username","alias","connectedStatus","orgId"}`. Non-zero exit or
+   `connectedStatus != "Connected"` ⇒ stop, ask the user to log in themselves.
+2. **Dry-run?** — offer by default. In dry-run, Phase 1 (preflight) and Phase 2's read/diff steps still run; Phase 2's `FieldPermissions` writes and Phases 3-5 (deploy) are skipped and recorded as `pending — not run (dry-run)`.
+3. **TPM Data Connector installed and active** — cannot be verified programmatically. Ask the user, spelling out the exact navigation steps rather than just naming the setting: *"Can you confirm the TPM Data Connector is Active? 1) Go to Setup → Data Cloud Setup. 2) In the left nav, under EXTERNAL INTEGRATIONS, click Other Connectors. 3) Find 'TPM Data Connector' in the list and check its status."* Wait for an explicit yes. If missing or inactive, **stop** — tell the user we cannot proceed without the TPM Data Connector being active, and explain the two different paths depending on org type:
+   - **Production orgs** — it's typically auto-installed within ~24h of Processing Service pairing, provided the org has a Data Cloud license. If both prerequisites are met, ask the user to wait and retry; if either isn't met (no pairing yet, or no Data Cloud license), that's the real blocker to resolve first.
+   - **Sandbox orgs** — auto-install commonly does not happen; it typically needs to be activated manually under EXTERNAL INTEGRATIONS → Other Connectors. Tell the user this is expected in sandboxes and ask them to activate it there, then confirm before continuing.
+   Re-run this check once the user confirms it's Active.
+4. **Salesforce CRM Home org connection** — cannot be verified programmatically. Ask the user, spelling out the exact navigation steps: *"Can you confirm the Salesforce CRM Home org connection is Active? 1) Go to Setup → Data Cloud Setup. 2) In the left nav, under SALESFORCE INTEGRATIONS, click Salesforce CRM. 3) Check that the Home org connection status is Active."* Wait for an explicit yes. If missing/inactive, **stop** — tell the user we cannot proceed without this connection being active (Phase 2's field-permission grants require the `Data Cloud Salesforce Connector` permission set, which won't exist until this connection is configured) — ask them to activate/configure it first, then re-run this check.
+5. **Permission set(s) for the TPM Admin persona + GenieAdmin permission set confirmed assigned** — when invoked as a delegated step from `consumer-goods-tpe-dashboard-configure`, it passes through both results already confirmed in its own earlier phases; reuse them, don't re-ask or re-query. When invoked standalone, confirm each directly:
+   - **Permission set(s) for the TPM Admin persona** — "TPM Admin persona" is a role, not an actual permission set name; the org-specific permission set backing that persona (name/assignment) cannot be verified programmatically. Ask the user to confirm: *"Is the permission set(s) required for the TPM Admin persona assigned to &lt;username&gt;?"* Wait for an explicit yes.
+   - **GenieAdmin** — resolve its Label first (never show the API `Name` to the user), then check the assignment:
+     ```bash
+     sf data query --target-org <username> --query "SELECT Label FROM PermissionSet WHERE Name = 'GenieAdmin'"
+     sf data query --target-org <username> \
+       --query "SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE Assignee.Username = '<username>' AND PermissionSet.Name = 'GenieAdmin'"
+     ```
+     Missing ⇒ tell the user the Label from the first query (e.g. *"User &lt;username&gt; is missing the &lt;Label&gt; permission set. Assign it now?"*) and ask permission to assign before continuing:
+     ```bash
+     sf data create record --sobject PermissionSetAssignment \
+       --values "AssigneeId=<userId> PermissionSetId=<psId>" --target-org <username>
+     ```
+     If declined, skip and note it in the report.
+6. **Namespace (`NS`)** — when invoked as a delegated step, `consumer-goods-tpe-dashboard-configure` passes through its already-detected `NS` (raw namespace string); reuse it, don't re-detect. When invoked standalone, detect it once yourself, before Phase 1, with the sibling script:
+   ```bash
+   node ./scripts/detect-namespace.js --target-org <username>
+   ```
+   Prints `{"NS","NS_SEGMENT","NS_APEX","NS_FIELD"}` as one line of JSON. Store all four and reuse everywhere below.
+
+
+## Phase 1 — Preflight
+
+2. **Baseline for later verification** — capture the latest `DataKitDeploymentLog` Id now, before any deploy work, to avoid a `CreatedDate` clock-skew false-negative in Phase 5:
+   ```bash
+   sf data query --target-org <username> \
+     --query "SELECT Id FROM DataKitDeploymentLog ORDER BY CreatedDate DESC LIMIT 1" --json
+   ```
+   Store as `LAST_ID_BEFORE_DEPLOY` (empty if zero rows).
+3. **Download & unzip `CGCloudAddons`** — this skill fetches it itself rather than asking the user to do it manually.
+   ```bash
+   node ./scripts/download-static-resource.js \
+     --target-org <username> --name CGCloudAddons
+   ```
+   Capture `STATIC_RESOURCE_PATH=<dir>` from stdout as `<addons_root>` — every path below is relative to it (e.g. `<addons_root>/TPM/Accruals/TPM Accruals Data Kit`). Zero `StaticResource` rows ⇒ **block**: the package version installed in this org doesn't ship `CGCloudAddons`. Any other script failure ⇒ block and relay its stderr verbatim.
+
+## Phase 2 — Field permissions for CRM streams (derived from the downloaded package)
+
+Two sibling scripts drive this phase — never hand-roll the parsing or the grant calls; see each script's own docstring for exactly what it does and why:
+
+1. **Extract** the `{sobject, fields[]}` list from the downloaded package (read-only, always safe to run):
+   ```bash
+   node ./scripts/extract-crm-field-permissions.js \
+     --dir "<addons_root>/TPM/Accruals/TPM Accruals Data Kit/force-app/main/default/dataSourceObjects" \
+     > /tmp/crm-field-permissions.json
+   ```
+   Zero entries in the output ⇒ block and report — shouldn't happen if Phase 1 succeeded.
+2. **Get the diff to update, silently** (the script's own `--dry-run` — read-only: permission set, `sobject/describe`, existing `FieldPermissions`/`ObjectPermissions` rows) — don't show the user anything yet, this is just to find out whether there's anything to do:
+   ```bash
+   node ./scripts/update-field-permissions.js \
+     --target-org <username> --input /tmp/crm-field-permissions.json --dry-run
+   ```
+   `{"error":"permission_set_not_found",...}` ⇒ stop this phase, mark it blocked, and tell the user: *"Could not find the 'Data Cloud Salesforce Connector' permission set — a likely explanation is that Salesforce CRM hasn't been configured yet (Setup → Data Cloud → Salesforce CRM). Please configure that first, then re-run this phase."*
+3. **Only if `wouldGrant` or `objectWouldGrant` is non-empty**, show the user exactly that diff (not the full extracted list) and get an explicit go-ahead before writing anything. If both are empty, everything's already granted — skip straight to step 5, no confirmation needed.
+4. **On confirmation, run it for real** — add-only at both field and object level (see script docstring for exact semantics):
+   ```bash
+   node ./scripts/update-field-permissions.js \
+     --target-org <username> --input /tmp/crm-field-permissions.json
+   ```
+   Exit code `3` (or a non-empty `failed[]`/`objectFailed[]`) ⇒ don't guess a workaround — prompt the user to do it manually via Setup → Permission Sets → Data Cloud Salesforce Connector → Object Settings, using exactly the `failed[]`/`objectFailed[]` list, and note each in the report.
+5. Record pass/blocked/pending, and the touched-field/object outcome (`granted`/`alreadyGranted`/`notFlsEligible`/`failed`, `objectGranted`/`objectAlreadyGranted`/`objectFailed`), for the final report. Dry-run mode (never proceed to step 4 when in dry run mode as it updates permissions, step1 and step2 can be run as they are read only)
+6. `objectGranted`/`objectAlreadyGranted` entries with `permissionsViewAllRecords: false` are expected for a small, fixed set of sobjects (currently just Product2) whose license blocks that flag — this is a known platform restriction the script applies silently; don't flag it to the user or treat it as something needing manual Setup action.
+
+## Phase 3 — Prepare and deploy data kit metadata
+
+1. In `<addons_root>/TPM/Accruals/TPM Accruals Data Kit`, find-and-replace every instance of the placeholder `__SF_ORG_ID__` with the org's 15-digit Id. Get the org Id via the following sibling script
+   ```bash
+   node ./scripts/sf-rest.js org-status --target-org <username>
+   ```
+   Take the `orgId` field from the printed JSON and truncate it to 15 chars (this call is cheap and idempotent — always re-run it here rather than relying on the Inputs step 1 result still being in context).
+2. Deploy from that folder:
+   ```bash
+   sf project deploy start --target-org <username>
+   ```
+
+## Phase 4 — Deploy DMO mappings and run the deployment script
+
+1. **DMO mappings** — maps the data kit's DLOs to Data 360 DMOs. From `<addons_root>/TPM/Accruals/DmoMappings`:
+   ```bash
+   sf project deploy start --target-org <username>
+   ```
+2. **Deployment script** — from `<addons_root>/TPM/Accruals/Accruals Data Kit Deployment Scripts`:
+   ```bash
+   SF_ORG_ALIAS=<username> node deploy-tpm-tpe.js
+   ```
+   This script POSTs to `/services/data/v67.0/actions/custom/flow/sfdatakit__DeployDataKitComponents` and returns an async Flow interview guid immediately; that response alone doesn't mean success — always confirm via the `DataKitDeploymentLog` check in Phase 5. This script runs from inside the downloaded/unzipped static resource.
+
+## Phase 5 — Verify
+
+```bash
+sf data query --target-org <username> \
+  --query "SELECT Id, DeploymentStatus, ComponentName, DeploymentError, CreatedDate FROM DataKitDeploymentLog WHERE Id > '<LAST_ID_BEFORE_DEPLOY>' ORDER BY CreatedDate DESC"
+```
+
+Every row for this run must have `DeploymentStatus = 'Successful'` and a blank `DeploymentError`. **Never claim success while any row is `Failure` or has a non-empty error.**
+
+Alternative UI check: Data Cloud Setup → Data Kits → TPM Accruals → Local Deployment History → status `Successful`.
+
+## Known gotchas
+
+- `FlowDefinition` is **not** SOQL-queryable — don't probe it for readiness.
+- An `sfdatakit__DeployDataKitComponents` ApexClass probe can return 0 rows even when the framework is live — prefer probing `DataKitDeploymentLog` directly (Phase 5), never the Apex class.
+
+## Rules
+
+- Never claim success while any `DataKitDeploymentLog` row for this run is `Failure` or has a non-empty `DeploymentError`.
+- Only ever read the `CGCloudAddons` `StaticResource` (via `download-static-resource.js`) — never deploy or modify it; the org's own `sf`-authenticated access token drives the download, never a hardcoded credential.
+- Never probe `FlowDefinition` or the `sfdatakit__DeployDataKitComponents` Apex class for readiness — probe `DataKitDeploymentLog` instead.
+- Never consult the org-shipped `README.md` (or any other in-package documentation bundled inside `CGCloudAddons`) for deployment guidance — follow this skill's phases exactly as written. If a script name or path documented here doesn't match what's actually in the downloaded package, that's a bug in this skill to fix (update the skill itself), not a cue to switch to package docs at runtime.
+- If a script or folder is missing from the downloaded folder, do not guess or change the scripts. e.g.: never change the script `deploy-tpm-tpe.js`.
+- Never run `update-field-permissions.js` without `--dry-run` first. If its `wouldGrant`/`objectWouldGrant` come back non-empty, never run for real without showing the user that exact diff and getting an explicit go-ahead — same as any other write in this skill. If both are empty, no confirmation is needed; proceed straight to reporting.
+- `update-field-permissions.js` only ever adds — a new `FieldPermissions`/`ObjectPermissions` row where none existed, or flipping an existing row's off flag (`PermissionsRead`, or `PermissionsViewAllRecords` at the object level) to `true`. Never call it in a way that deletes a row, weakens an existing grant, or touches `PermissionsCreate`/`Edit`/`Delete`/`ModifyAllRecords`.
+- Never guess a workaround when the `sfdc_a360_sfcrm_data_extract` ("Data Cloud Salesforce Connector") permission set is missing or a field/object ends up in `update-field-permissions.js`'s `failed[]`/`objectFailed[]` — stop and prompt the user to grant field-level or object-level security manually via Setup (see Phase 2).
+
+## Report
+
+Produce a final report (pass/blocked/pending) covering: CRM stream field permissions (per-object field list from `extract-crm-field-permissions.js`, and each field's `granted`/`alreadyGranted`/`notFlsEligible`/`failed` outcome from `update-field-permissions.js` — flag any `notFlsEligible` entry with `onObject: false` separately, since that's a package/org data mismatch, not a normal skip), CRM stream object-level permissions (each sobject's `objectGranted`/`objectAlreadyGranted`/`objectFailed` outcome from the same script — a `permissionsViewAllRecords: false` on Product2 specifically is expected and not worth calling out), preflight (connector status), metadata deploy, DMO mapping deploy, deployment script run, and the `DataKitDeploymentLog` verification result (row count, any failures). This is exactly what `consumer-goods-tpe-dashboard-configure` Step 7 relays as its own result when this skill is invoked via delegation.
+
+**When invoked via delegation** (the calling skill used the `Skill` tool to reach this file, rather than the user directly): this report is an intermediate result, not the end of the task. Return it to the calling skill and let it continue with its own next phase — do not present this report to the user as the final answer and stop. Only surface this report directly to the user when this skill was invoked standalone.

package/skills/consumer-goods-tpe-datakit-deploy/scripts/detect-namespace.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Detects this org's namespace and derives every prefixed form this skill
+ * needs, replacing the manual "run sf, read the JSON, compute NS_* by hand"
+ * steps in SKILL.md's Namespace detection section. Same canonical procedure
+ * as `setup-tpe-dashboard`'s Namespace detection step — never re-derive a
+ * different way:
+ *   1. `sf package installed list` — find the "Consumer Goods Cloud" entry,
+ *      NS = its SubscriberPackageNamespace.
+ *   2. Not found (source-deployed/dev-beta org) ⇒ `sf org display`'s
+ *      `result.namespace`.
+ *   3. Still null/blank ⇒ NS = "" (genuinely unnamespaced org).
+ *
+ * CLI usage:
+ *   node detect-namespace.js --target-org <username>
+ *
+ * Prints one line of JSON to stdout: {"NS","NS_SEGMENT","NS_APEX","NS_FIELD"}.
+ * Exit codes: 0 = success, 2 = usage/CLI error.
+ */
+
+const { execFileSync } = require('child_process');
+
+function sfJson(cliArgs) {
+  const raw = execFileSync('sf', cliArgs, { encoding: 'utf8' });
+  return JSON.parse(raw).result;
+}
+
+function detectNamespace(targetOrg) {
+  const packages = sfJson([
+    'package', 'installed', 'list',
+    '--target-org', targetOrg, '--json',
+  ]);
+  const cgCloud = (packages || []).find(
+    (p) => p.SubscriberPackageName === 'Consumer Goods Cloud'
+  );
+  if (cgCloud && cgCloud.SubscriberPackageNamespace) {
+    return cgCloud.SubscriberPackageNamespace;
+  }
+
+  const { namespace } = sfJson([
+    'org', 'display',
+    '--target-org', targetOrg, '--json',
+  ]);
+  return namespace || '';
+}
+
+function deriveForms(NS) {
+  return {
+    NS,
+    NS_SEGMENT: NS ? `${NS}/` : '',
+    NS_APEX: NS ? `${NS}.` : '',
+    NS_FIELD: NS ? `${NS}__` : '',
+  };
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    args[token.slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function requireArg(args, name) {
+  if (!args[name]) {
+    console.error(`Missing required --${name}`);
+    process.exit(2);
+  }
+  return args[name];
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const targetOrg = requireArg(args, 'target-org');
+  const NS = detectNamespace(targetOrg);
+  process.stdout.write(JSON.stringify(deriveForms(NS)));
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { detectNamespace, deriveForms };

package/skills/consumer-goods-tpe-datakit-deploy/scripts/download-static-resource.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Downloads and unzips a StaticResource from an authenticated org, reusing
+ * the same contract as `downloadStaticResource` in
+ * `packages/liability-accruals/setup/steps/01-download-static-resource.js`
+ * (SOQL for the StaticResource Id, then an authenticated GET against
+ * `<instanceUrl>/services/data/v<apiVersion>/sobjects/StaticResource/<id>/Body`,
+ * then extract the zip) — reimplemented here with Node's built-in fetch
+ * instead of `curl`, so this skill has no dependency on that script. Zip
+ * extraction shells out to a platform-native tool rather than an npm
+ * package (`adm-zip`, etc.) so this skill stays dependency-free and portable
+ * across machines that clone/copy it standalone, per this repo's
+ * self-contained-skills rule:
+ *   - Windows: `tar -xf` — the `tar.exe` bundled with Windows 10 (1803+) and
+ *     11 is bsdtar, which reads zip archives transparently.
+ *   - macOS/Linux: `unzip` — preinstalled on macOS; on Linux it's a common
+ *     but not universal package (missing ⇒ clear error telling the user to
+ *     install it). GNU `tar` on Linux cannot read zip, so `tar` is not a
+ *     safe cross-platform substitute there.
+ *
+ * One deliberate deviation from that reference: `getOrgDetails()` there
+ * reads `sf org display --json`'s `result.accessToken` directly, which no
+ * longer returns a real token on `sf` CLI >= 2.136.8 (that field becomes a
+ * redacted hint string pointing at `sf org auth show-access-token` —
+ * confirmed live against this repo's own dev org). `getAccessToken()` in
+ * ``./sf-rest` is version-gated to handle both cases; the token is never
+ * printed.
+ *
+ * Usage:
+ *   node download-static-resource.js \
+ *     --target-org <username> \
+ *     --name CGCloudAddons \
+ *     [--output-dir <dir>]   # defaults to a fresh dir under the OS temp dir
+ *
+ * Writes <output-dir>/<name>.zip and unzips it to <output-dir>/<name>/.
+ * Prints STATIC_RESOURCE_PATH=<absolute unzipped dir> on success.
+ *
+ * Exit codes: 0 = success, 1 = resource not found, org not connected, or
+ * download/unzip failure.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { sfJson, getAccessToken } = require('./sf-rest');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    args[token.slice(2)] = argv[i + 1];
+    i += 1;
+  }
+  return args;
+}
+
+function requireArg(args, name) {
+  if (!args[name]) {
+    console.error(`Missing required --${name}`);
+    process.exit(1);
+  }
+  return args[name];
+}
+
+function unzipTo(zipPath, destDir) {
+  const [cmd, cmdArgs] = process.platform === 'win32'
+    ? ['tar', ['-xf', zipPath, '-C', destDir]]
+    : ['unzip', ['-o', '-q', zipPath, '-d', destDir]];
+  const attemptedCommand = `${cmd} ${cmdArgs.join(' ')}`;
+  try {
+    execFileSync(cmd, cmdArgs, { stdio: 'pipe' });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.error(
+        `download-static-resource: command failed — "${attemptedCommand}" — "${cmd}" 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'
+        }. If a different extraction command is available on this machine, run it manually against "${zipPath}" -> "${destDir}" and re-invoke this script with the same --output-dir to skip re-downloading.`
+      );
+      process.exit(1);
+    }
+    console.error(
+      `download-static-resource: command failed — "${attemptedCommand}" — ${error.message}`
+    );
+    process.exit(1);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const targetOrg = requireArg(args, 'target-org');
+  const name = requireArg(args, 'name');
+  const outputDir =
+    args['output-dir'] ||
+    fs.mkdtempSync(path.join(os.tmpdir(), 'cgcloud-static-resource-'));
+
+  const queryResult = sfJson([
+    'data',
+    'query',
+    '--target-org',
+    targetOrg,
+    '--query',
+    `SELECT Id, Name FROM StaticResource WHERE Name='${name}'`,
+    '--json',
+  ]);
+  if (!queryResult.records || queryResult.records.length < 1) {
+    console.error(
+      `download-static-resource: no StaticResource named "${name}" found in ${targetOrg} — confirm the package version installed in this org includes it.`
+    );
+    process.exit(1);
+  }
+  const staticResourceId = queryResult.records[0].Id;
+
+  const orgDetails = sfJson(['org', 'display', '--target-org', targetOrg, '--json']);
+  const instanceUrl = orgDetails.instanceUrl;
+  const apiVersion = orgDetails.apiVersion || '60.0';
+  const accessToken = getAccessToken(targetOrg);
+
+  const bodyUrl = `${instanceUrl}/services/data/v${apiVersion}/sobjects/StaticResource/${staticResourceId}/Body`;
+  const response = await fetch(bodyUrl, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+  if (!response.ok) {
+    console.error(
+      `download-static-resource: download failed with HTTP ${response.status}`
+    );
+    process.exit(1);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+
+  fs.mkdirSync(outputDir, { recursive: true });
+  const zipPath = path.join(outputDir, `${name}.zip`);
+  fs.writeFileSync(zipPath, buffer);
+
+  const unzipDir = path.join(outputDir, name);
+  if (fs.existsSync(unzipDir)) {
+    fs.rmSync(unzipDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(unzipDir, { recursive: true });
+  unzipTo(zipPath, unzipDir);
+
+  console.log(`STATIC_RESOURCE_PATH=${path.resolve(unzipDir)}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});