@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/scripts/classify-action-surface.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Deterministic verify-phase classifier for the ITSM Intelligence permset-assign flow.
+//
+// Reads the `/services/data/v67.0/actions/custom/generatePromptResponse`
+// response capture and decides whether the ITSM Intelligence prompt-template
+// invocable actions (Fulfiller-only — `svc_itsm_intelligence__*`) are
+// surfaced for the running user. Replaces the prose "grep the response for
+// svc_itsm_intelligence__" step in Phase 4 (A9 — deterministic decisions
+// belong in scripts). Employee agent actions (`svc_emp_intelligence__*`)
+// are out of scope for this skill.
+//
+// Rules:
+//   - Accepts both response shapes for `actions`:
+//       (a) legacy `{ actions: [ { name, ... }, ... ] }`
+//       (b) newer  `{ actions: { <fullyQualifiedName>: {...}, ... } }`
+//     Either wrapped by `data.result` (CLI envelope) or at top level.
+//   - If `expectedActions` (CSV of specific action API names) is provided,
+//     partition each into `present` / `missing` by exact name match on the
+//     extracted names. `verdict`:
+//       * SURFACED — every expected action is present.
+//       * PARTIAL  — at least one is present but not all.
+//       * MISSING  — none are present.
+//   - If `expectedActions` is omitted, look for AT LEAST ONE action name
+//     starting with `svc_itsm_intelligence__`.
+//       * SURFACED — one or more found; `present` lists them, `missing` is [].
+//       * MISSING  — none found; `missing` is [] (no explicit expectation set).
+//   - Envelope missing/failed / unexpected shape ⇒ CANNOT-CONFIRM.
+//
+// Usage:
+//   node classify-action-surface.mjs <generate-prompt-response.json> [expectedActions-csv]
+//
+// Emits a single JSON object to stdout:
+//   { present: [name, ...],
+//     missing: [name, ...],
+//     totalItsmActionsSeen: <int>,
+//     verdict: "SURFACED" | "PARTIAL" | "MISSING" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable bodies; verdict carries the decision.
+
+import { readFileSync } from 'node:fs';
+
+const [responsePath, expectedCsv] = process.argv.slice(2);
+if (!responsePath) {
+  process.stderr.write('usage: node classify-action-surface.mjs <generate-prompt-response.json> [expectedActions-csv]\n');
+  process.exit(2);
+}
+
+function emit(verdict, extras, reasons) {
+  process.stdout.write(JSON.stringify({
+    present: extras.present ?? [],
+    missing: extras.missing ?? [],
+    totalItsmActionsSeen: extras.totalItsmActionsSeen ?? 0,
+    verdict,
+    reasons,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+let text;
+try {
+  text = readFileSync(responsePath, 'utf8').trim();
+} catch (e) {
+  emit('CANNOT-CONFIRM', {}, [`unreadable file at ${responsePath}: ${e?.message ?? e}`]);
+}
+if (!text) emit('CANNOT-CONFIRM', {}, [`empty file: ${responsePath}`]);
+
+let data;
+try {
+  data = JSON.parse(text);
+} catch (e) {
+  emit('CANNOT-CONFIRM', {}, [`invalid JSON at ${responsePath}: ${e?.message ?? e}`]);
+}
+if (!data || typeof data !== 'object') {
+  emit('CANNOT-CONFIRM', {}, [`non-object JSON at ${responsePath}`]);
+}
+if (typeof data.status === 'number' && data.status !== 0) {
+  emit('CANNOT-CONFIRM', {}, [`sf api request at ${responsePath} failed with status ${data.status}`]);
+}
+
+// The generatePromptResponse endpoint has two observed response shapes; accept
+// both so a valid surface never mis-classifies as CANNOT-CONFIRM:
+//   (a) legacy `{ actions: [ { name, ... }, ... ] }`
+//   (b) newer  `{ actions: { <fullyQualifiedName>: {...}, ... } }`
+// Both forms may also be wrapped by the CLI envelope under `data.result`.
+function extractNames(actionsField) {
+  if (Array.isArray(actionsField)) {
+    return actionsField
+      .map((a) => (a && typeof a.name === 'string' ? a.name : null))
+      .filter((n) => n !== null);
+  }
+  if (actionsField && typeof actionsField === 'object') {
+    return Object.keys(actionsField);
+  }
+  return null;
+}
+const names = extractNames(data.actions) ?? extractNames(data.result?.actions);
+if (names === null) {
+  emit('CANNOT-CONFIRM', {}, [
+    `response body has no \`actions\` array or object — expected the /actions/custom/generatePromptResponse envelope. Confirm the CLI wrote the full body to ${responsePath}.`,
+  ]);
+}
+
+const itsmNames = names.filter((n) => n.startsWith('svc_itsm_intelligence__'));
+
+const expected = (expectedCsv ?? '')
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+
+if (expected.length > 0) {
+  const present = expected.filter((e) => names.includes(e));
+  const missing = expected.filter((e) => !names.includes(e));
+  let verdict;
+  if (missing.length === 0) verdict = 'SURFACED';
+  else if (present.length === 0) verdict = 'MISSING';
+  else verdict = 'PARTIAL';
+  const reasons = [
+    `Checked ${expected.length} expected action name(s): ${present.length} present, ${missing.length} missing.`,
+  ];
+  if (missing.length > 0) {
+    reasons.push(`Missing: ${missing.join(', ')}. A permset write can succeed while the target action set is still ungated by the assigned permset (cache, wrong permset). Do not report success.`);
+  }
+  if (itsmNames.length > 0 && (present.length !== itsmNames.length || missing.length > 0)) {
+    reasons.push(`Response contains ${itsmNames.length} svc_itsm_intelligence__ action(s) overall: ${itsmNames.slice(0, 20).join(', ')}${itsmNames.length > 20 ? ', …' : ''}.`);
+  }
+  emit(verdict, { present, missing, totalItsmActionsSeen: itsmNames.length }, reasons);
+}
+
+// No explicit expectation — surface if ANY ITSM Intelligence action is present.
+if (itsmNames.length === 0) {
+  emit('MISSING', { present: [], missing: [], totalItsmActionsSeen: 0 }, [
+    'No `svc_itsm_intelligence__` invocable actions were returned for this user. Assignment may have succeeded but the actions are not surfaced — try a session refresh, or the assigned persona permset does not gate the target actions.',
+  ]);
+}
+emit('SURFACED', { present: itsmNames, missing: [], totalItsmActionsSeen: itsmNames.length }, [
+  `Found ${itsmNames.length} ITSM Intelligence invocable action(s) surfaced for this user.`,
+]);

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/scripts/classify-assignment-state.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Deterministic idempotency classifier for the ITSM Intelligence permset-assign flow.
+//
+// Reads the `sf data query --json` captures:
+//   - PermissionSetAssignment (permset ↔ user) for the target user + permset
+//   - PermissionSetLicenseAssign (PSL ↔ user) for the target user + PSL
+//     — ONLY when the selected permset actually has a backing license.
+//       Pass the sentinel `NO-PSL` in place of the PSLA path when
+//       `classify-permset-availability.mjs` reported `needsPsl:false`
+//       (standalone permset — no PSL query, no PSL POST in Phase 2d).
+// and decides whether the Phase 2d write should be skipped.
+//
+// Rules (A9):
+//   - needsPsl AND both rows present ⇒ needsWrite=false (already fully assigned).
+//   - needsPsl AND either row missing ⇒ needsWrite=true (assign the missing
+//     piece; the workflow's Phase 2d handles PSL before permset regardless of
+//     which one is currently missing to preserve the write-order invariant).
+//   - !needsPsl (pslaPath === "NO-PSL"):
+//       * permsetAssigned ⇒ needsWrite=false (nothing to write).
+//       * !permsetAssigned ⇒ needsWrite=true (assign the permset only —
+//         Phase 2d MUST skip the PSL POST).
+//     `licenseAssigned` is reported as null in this branch (not applicable).
+//   - Query envelope missing/failed ⇒ CANNOT-CONFIRM; surface it and stop.
+//
+// Usage:
+//   node classify-assignment-state.mjs <psa-existing.json> <psla-existing.json | NO-PSL>
+//
+// Emits a single JSON object to stdout:
+//   { permsetAssigned, licenseAssigned, needsWrite,
+//     verdict: "NEEDS-WRITE" | "ALREADY-ASSIGNED" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable bodies; verdict carries the decision.
+
+import { readFileSync } from 'node:fs';
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object') return { ok: false, reason: `non-object JSON at ${path}` };
+    if (typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+const argv = process.argv.slice(2).filter((a) => !!a);
+if (argv.length < 2) {
+  process.stderr.write('usage: node classify-assignment-state.mjs <psa-existing.json> <psla-existing.json | NO-PSL>\n');
+  process.exit(2);
+}
+const [psaPath, pslaArg] = argv;
+const needsPsl = pslaArg !== 'NO-PSL';
+
+const psa = readEnvelope(psaPath);
+const psla = needsPsl ? readEnvelope(pslaArg) : { ok: true, records: [], skipped: true };
+
+const readErrors = [psa, psla].filter((r) => !r.ok).map((r) => r.reason);
+if (readErrors.length) {
+  process.stdout.write(JSON.stringify({
+    permsetAssigned: null, licenseAssigned: null, needsWrite: null,
+    verdict: 'CANNOT-CONFIRM',
+    reasons: readErrors,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+const permsetAssigned = psa.records.length > 0;
+const licenseAssigned = needsPsl ? psla.records.length > 0 : null;
+const needsWrite = needsPsl
+  ? !(permsetAssigned && licenseAssigned)
+  : !permsetAssigned;
+
+const verdict = needsWrite ? 'NEEDS-WRITE' : 'ALREADY-ASSIGNED';
+const reasons = [
+  `PermissionSetAssignment: ${permsetAssigned ? 'present' : 'missing'} (${psa.records.length} row${psa.records.length === 1 ? '' : 's'}).`,
+  needsPsl
+    ? `PermissionSetLicenseAssign: ${licenseAssigned ? 'present' : 'missing'} (${psla.records.length} row${psla.records.length === 1 ? '' : 's'}).`
+    : 'PermissionSetLicenseAssign: not applicable — the selected permission set has no backing LicenseId (standalone-permset flow; PSL SOQL + POST are skipped).',
+];
+reasons.push(
+  needsWrite
+    ? (needsPsl
+      ? 'At least one assignment is missing — proceed to Phase 2c confirm-to-write, then Phase 2d (PSL first, permset second).'
+      : 'Permission set assignment is missing — proceed to Phase 2c confirm-to-write, then Phase 2d permset assign ONLY (skip the PSL POST).')
+    : (needsPsl
+      ? 'Both the permission set and its backing license are already assigned to this user — skip Phase 2d, go straight to Phase 4 verify.'
+      : 'The permission set is already assigned to this user (no backing license required) — skip Phase 2d, go straight to Phase 4 verify.')
+);
+
+process.stdout.write(JSON.stringify({
+  permsetAssigned, licenseAssigned, needsWrite, verdict, reasons,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/scripts/classify-permset-availability.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// Deterministic branch classifier for the Fulfiller persona permset-assign flow.
+//
+// Reads ONE input:
+//   - PermissionSet query capture (from `sf data query --json`) for the four
+//     Core-shipped Fulfiller persona permsets:
+//       * IncidentFulfiller
+//       * ProblemFulfillerPermSet
+//       * ChangeRequestFulfillerPermSet
+//       * ReleaseManagerPermSet
+//     (namespace `force`, not a managed-package namespace)
+//
+// Rules (A9):
+//   - `verdict:"ASSIGN"`      — ≥1 of the four personas is present. Caller
+//                                asks the user which persona to assign; do NOT
+//                                auto-select.
+//   - `verdict:"HAND-OFF"`    — none of the four present. The ITSM AddOn(s)
+//                                are not provisioned; permset-assign is a
+//                                no-op. Hand off to the studio validate skill
+//                                so the AddOn(s) can be enabled first.
+//   - `verdict:"CANNOT-CONFIRM"` — query envelope missing / unparseable.
+//
+// Usage:
+//   node classify-permset-availability.mjs <permsets.json>
+//
+// Emits a single JSON object to stdout:
+//   { personasFound: [Name, ...],
+//     personasMissing: [Name, ...],
+//     candidates: [{ Id, Name, Label, LicenseId, needsPsl }, ...],
+//     verdict: "ASSIGN" | "HAND-OFF" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// `candidates` includes only rows for the four known persona Names; unrelated
+// rows in the query result are filtered out. `needsPsl` is derived per-row
+// from `LicenseId !== null`. Exit is always 0 on parseable bodies; verdict
+// carries the branch decision. Exit 2 on missing argv.
+
+import { readFileSync } from 'node:fs';
+
+const KNOWN_PERSONAS = [
+  'IncidentFulfiller',
+  'ProblemFulfillerPermSet',
+  'ChangeRequestFulfillerPermSet',
+  'ReleaseManagerPermSet',
+];
+
+function readEnvelope(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false, reason: `empty file: ${path}` };
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object') return { ok: false, reason: `non-object JSON at ${path}` };
+    if (typeof data.status === 'number' && data.status !== 0) {
+      return { ok: false, reason: `sf data query at ${path} failed with status ${data.status}` };
+    }
+    const records = Array.isArray(data.result?.records) ? data.result.records : null;
+    if (!records) return { ok: false, reason: `missing result.records[] at ${path}` };
+    return { ok: true, records };
+  } catch (e) {
+    return { ok: false, reason: `unreadable/invalid JSON at ${path}: ${e?.message ?? e}` };
+  }
+}
+
+const [psPath] = process.argv.slice(2);
+if (!psPath) {
+  process.stderr.write('usage: node classify-permset-availability.mjs <permsets.json>\n');
+  process.exit(2);
+}
+
+const ps = readEnvelope(psPath);
+if (!ps.ok) {
+  process.stdout.write(JSON.stringify({
+    personasFound: [],
+    personasMissing: [...KNOWN_PERSONAS],
+    candidates: [],
+    verdict: 'CANNOT-CONFIRM',
+    reasons: [ps.reason],
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+// Filter to only the five known persona Names — drop any unrelated rows.
+const knownRows = ps.records.filter((r) => KNOWN_PERSONAS.includes(r?.Name));
+const foundNames = knownRows.map((r) => r.Name);
+const personasFound = KNOWN_PERSONAS.filter((n) => foundNames.includes(n));
+const personasMissing = KNOWN_PERSONAS.filter((n) => !foundNames.includes(n));
+
+const candidates = knownRows.map((r) => ({
+  Id: r.Id ?? null,
+  Name: r.Name ?? null,
+  Label: r.Label ?? null,
+  LicenseId: r.LicenseId ?? null,
+  needsPsl: (r.LicenseId ?? null) !== null,
+}));
+
+const reasons = [];
+let verdict;
+if (personasFound.length === 0) {
+  verdict = 'HAND-OFF';
+  reasons.push('None of the four Core-shipped Fulfiller persona permsets (IncidentFulfiller, ProblemFulfillerPermSet, ChangeRequestFulfillerPermSet, ReleaseManagerPermSet) is present on this org — the ITSM AddOn(s) are not provisioned.');
+  reasons.push('Permset-assign cannot fix this; hand off to service-itsm-agentic-setup-agentforce-studio-validate.');
+} else {
+  verdict = 'ASSIGN';
+  reasons.push(`Found ${personasFound.length} of 4 Fulfiller persona permset(s) on this org: ${personasFound.join(', ')}.`);
+  if (personasMissing.length > 0) {
+    reasons.push(`Not provisioned (AddOn(s) missing for these personas): ${personasMissing.join(', ')}.`);
+  }
+  const standalone = candidates.filter((c) => !c.needsPsl).map((c) => c.Name);
+  if (standalone.length > 0) {
+    reasons.push(`Standalone-permset flow (no backing LicenseId — Phase 2 skips PSL SOQL/POST if selected): ${standalone.join(', ')}.`);
+  }
+  reasons.push('Caller MUST ask the user which persona to assign before Phase 2 — do not auto-select. A Fulfiller commonly needs only one persona (e.g. only Incident).');
+}
+
+process.stdout.write(JSON.stringify({
+  personasFound,
+  personasMissing,
+  candidates,
+  verdict,
+  reasons,
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign/scripts/resolve-target-user.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Deterministic target-user resolver for the ITSM Intelligence permset-assign flow.
+//
+// Reads the `GET /services/data/v67.0/` capture (or an equivalent versions-list
+// response the CLI writes when hitting the API root), and extracts the running
+// user's Id from the `identity` URL. The URL shape is:
+//     https://<mydomain>.my.salesforce.com/id/<orgId 00D…>/<userId 005…>
+// so we take the LAST path segment and require it to start with `005` and be
+// 15 or 18 chars (case-preserving).
+//
+// This exists so no prose step ever tries to parse the identity URL by hand
+// (A9 — deterministic decisions belong in scripts).
+//
+// Usage:
+//   node resolve-target-user.mjs <api-root.json>
+//
+// Emits a single JSON object to stdout:
+//   { userId: "005…" | null,
+//     identity: "<full URL>" | null,
+//     verdict: "RESOLVED" | "CANNOT-CONFIRM",
+//     reasons: [...] }
+// Exit is always 0 on parseable bodies; verdict carries the decision.
+
+import { readFileSync } from 'node:fs';
+
+const [rootPath] = process.argv.slice(2);
+if (!rootPath) {
+  process.stderr.write('usage: node resolve-target-user.mjs <api-root.json>\n');
+  process.exit(2);
+}
+
+function fail(reasons) {
+  process.stdout.write(JSON.stringify({
+    userId: null, identity: null, verdict: 'CANNOT-CONFIRM', reasons,
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+let text;
+try {
+  text = readFileSync(rootPath, 'utf8').trim();
+} catch (e) {
+  fail([`unreadable file at ${rootPath}: ${e?.message ?? e}`]);
+}
+if (!text) fail([`empty file: ${rootPath}`]);
+
+let data;
+try {
+  data = JSON.parse(text);
+} catch (e) {
+  fail([`invalid JSON at ${rootPath}: ${e?.message ?? e}`]);
+}
+if (!data || typeof data !== 'object') fail([`non-object JSON at ${rootPath}`]);
+if (typeof data.status === 'number' && data.status !== 0) {
+  fail([`sf api request at ${rootPath} failed with status ${data.status}`]);
+}
+
+// `sf api request rest` returns the raw body directly; the API root response
+// contains `identity`, `rest`, and version fields at the top level.
+const identity = typeof data.identity === 'string'
+  ? data.identity
+  : (typeof data.result?.identity === 'string' ? data.result.identity : null);
+
+if (!identity) {
+  fail(['response body has no `identity` field — cannot resolve the running user without it. Confirm the org is reachable and re-run `sf api request rest "/services/data/v67.0/"`.']);
+}
+
+const segments = identity.split('/').filter(Boolean);
+const last = segments[segments.length - 1] ?? '';
+
+// Salesforce user Ids: 15-char case-sensitive or 18-char case-insensitive, prefix `005`.
+if (!/^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$/.test(last)) {
+  fail([
+    `identity URL trailing segment "${last}" does not match the expected user-Id shape (005 + 12 or 15 alphanum chars).`,
+    `full identity URL: ${identity}`,
+  ]);
+}
+
+process.stdout.write(JSON.stringify({
+  userId: last,
+  identity,
+  verdict: 'RESOLVED',
+  reasons: [
+    `Extracted running-user Id "${last}" from identity URL trailing path segment.`,
+  ],
+}, null, 2) + '\n');