@aifabrix/builder 2.53.1 → 2.55.0

package/lib/role-assistant/settings.js

@@ -13,7 +13,11 @@ const fs = require('../internal/fs-real-sync');
 const yaml = require('js-yaml');
 const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { loadRoleAssistantSettingsSchema } = require('../utils/schema-loader');
-const { SYSTEM_KIND_DIGITAL_WORKER } = require('../utils/role-assistant-paths');
+const {
+  SYSTEM_KIND_DIGITAL_WORKER,
+  WORKSPACE_ROLE_ASSISTANT,
+  bareRoleKey
+} = require('../utils/role-assistant-paths');
 
 function getRoleAssistantYamlPath(systemKey, options = {}) {
   const appPath = resolveExternalSystemPath(systemKey, options.pathOptions || {});
@@ -115,6 +119,48 @@ function resolveRoleAssistantSettingsVersion(settings) {
   return value.trim();
 }
 
+function defaultRoleAssistantSettings(systemKey) {
+  return {
+    apiVersion: 'aifabrix.ai/v1',
+    version: '1.0.0',
+    kind: 'RoleAssistantSettings',
+    roleKey: bareRoleKey(systemKey)
+  };
+}
+
+function mergeRoleAssistantSettings(existing, systemKey) {
+  const next = existing && typeof existing === 'object' ? { ...existing } : {};
+  const defaults = defaultRoleAssistantSettings(systemKey);
+  return {
+    ...defaults,
+    ...next,
+    apiVersion: defaults.apiVersion,
+    kind: defaults.kind,
+    roleKey: defaults.roleKey
+  };
+}
+
+function writeOrMergeRoleAssistantSettings(systemKey, options = {}) {
+  const filePath = getRoleAssistantYamlPath(systemKey, {
+    ...options,
+    pathOptions: {
+      ...(options.pathOptions || {}),
+      workspace: WORKSPACE_ROLE_ASSISTANT
+    }
+  });
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  let payload = defaultRoleAssistantSettings(systemKey);
+  if (!options.force && fs.existsSync(filePath)) {
+    try {
+      payload = mergeRoleAssistantSettings(parseRoleAssistantYaml(filePath), systemKey);
+    } catch {
+      payload = defaultRoleAssistantSettings(systemKey);
+    }
+  }
+  fs.writeFileSync(filePath, yaml.dump(payload, { lineWidth: -1 }), 'utf8');
+  return filePath;
+}
+
 module.exports = {
   SYSTEM_KIND_DIGITAL_WORKER,
   getRoleAssistantYamlPath,
@@ -122,5 +168,6 @@ module.exports = {
   readRoleAssistantSettings,
   resolveRoleAssistantEnvironmentSettings,
   resolveDocumentStorageKeyFromRoleAssistantSettings,
-  resolveRoleAssistantSettingsVersion
+  resolveRoleAssistantSettingsVersion,
+  writeOrMergeRoleAssistantSettings
 };

package/lib/role-assistant/test-case-assertion-row.js

@@ -0,0 +1,36 @@
+/**
+ * Shared assertion row helpers (pass/fail/warn/notes/skip).
+ * @fileoverview Kind flags for Role Assistant test result rows
+ */
+
+'use strict';
+
+function skipRow(id, message) {
+  return { id, passed: true, skip: true, kind: 'skip', message };
+}
+
+function notesRow(id, message) {
+  return { id, passed: true, notes: true, kind: 'notes', message };
+}
+
+function withKind(row) {
+  if (!row || row.kind) {
+    return row;
+  }
+  if (row.notes === true) {
+    return { ...row, kind: 'notes' };
+  }
+  if (row.skip === true) {
+    return { ...row, kind: 'skip' };
+  }
+  if (row.warn === true) {
+    return { ...row, kind: 'warn' };
+  }
+  return { ...row, kind: row.passed ? 'pass' : 'fail' };
+}
+
+module.exports = {
+  skipRow,
+  notesRow,
+  withKind
+};

package/lib/role-assistant/test-case-copy-bind.js

@@ -0,0 +1,77 @@
+/**
+ * Bind a Work Hub execution to the Role Assistant named on copy.
+ *
+ * @fileoverview Fail closed on mismatch; trust the CLI role when identity is absent
+ */
+
+'use strict';
+
+const {
+  bareRoleKey,
+  roleAssistantSystemKey
+} = require('../utils/role-assistant-paths');
+
+const PLACEHOLDER = new Set(['', 'unknown', 'none', 'null']);
+
+function throwCopyStatus(message, status) {
+  const err = new Error(message);
+  err.status = status;
+  throw err;
+}
+
+function usableIdentity(value) {
+  const token = String(value || '').trim();
+  if (!token || PLACEHOLDER.has(token.toLowerCase())) {
+    return '';
+  }
+  return token;
+}
+
+function pushIdentity(acc, value) {
+  const token = usableIdentity(value);
+  if (token) {
+    acc.push(token);
+  }
+}
+
+function boundIdentityTokens(status, result) {
+  const acc = [];
+  const task = result && result.task && typeof result.task === 'object' ? result.task : {};
+  pushIdentity(acc, status && status.assistantKey);
+  pushIdentity(acc, status && status.digitalWorkerKey);
+  pushIdentity(acc, result && result.assistantKey);
+  pushIdentity(acc, result && result.digitalWorkerKey);
+  pushIdentity(acc, task.assistantKey);
+  pushIdentity(acc, task.digitalWorkerKey);
+  pushIdentity(acc, task.activeBusinessRoleRef);
+  pushIdentity(acc, task.roleKey);
+  return [...new Set(acc)];
+}
+
+function identityMatchesSystem(token, systemKey) {
+  const expectedSystem = roleAssistantSystemKey(systemKey);
+  const expectedBare = bareRoleKey(systemKey).toLowerCase();
+  const lower = token.toLowerCase();
+  if (lower === expectedSystem.toLowerCase()) {
+    return true;
+  }
+  return bareRoleKey(token).toLowerCase() === expectedBare;
+}
+
+function assertCopyBoundToSystem(systemKey, status, result) {
+  const tokens = boundIdentityTokens(status, result);
+  if (tokens.length === 0) {
+    return { bound: false };
+  }
+  const mismatch = tokens.find((token) => !identityMatchesSystem(token, systemKey));
+  if (mismatch) {
+    throwCopyStatus('Execution belongs to a different Role Assistant', 409);
+  }
+  return { bound: true };
+}
+
+module.exports = {
+  throwCopyStatus,
+  boundIdentityTokens,
+  assertCopyBoundToSystem
+};

package/lib/role-assistant/test-case-copy-expected.js

@@ -0,0 +1,127 @@
+/**
+ * Derive copy input.message and expected.* from Work Hub reference payloads.
+ *
+ * @fileoverview No facts dump; do not invent a start message
+ */
+
+'use strict';
+
+const { collectObservedCapabilities } = require('./test-cases');
+const { throwCopyStatus } = require('./test-case-copy-bind');
+
+const PLACEHOLDER = new Set(['', 'unknown', 'none', 'null']);
+const STATUS_LIFECYCLE = {
+  completed: 'completed',
+  stopped: 'failed'
+};
+const OBJECTIVE_KEYS = new Set([
+  'objective',
+  'goal',
+  'planObjective',
+  'objectiveSummary',
+  'acceptedObjective'
+]);
+
+function usableText(value) {
+  const text = String(value || '').trim();
+  if (!text || PLACEHOLDER.has(text.toLowerCase())) {
+    return '';
+  }
+  return text;
+}
+
+function collectObjectiveStrings(value, acc, depth) {
+  if (depth > 8 || !value) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectObjectiveStrings(item, acc, depth + 1));
+    return;
+  }
+  if (typeof value !== 'object') {
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (OBJECTIVE_KEYS.has(key) && typeof child === 'string') {
+      const text = usableText(child);
+      if (text) {
+        acc.push(text);
+      }
+    } else if (child && typeof child === 'object') {
+      collectObjectiveStrings(child, acc, depth + 1);
+    }
+  }
+}
+
+function startMessageFromWorkReference(result) {
+  const goal = usableText(result && result.task && result.task.acceptedIntent && result.task.acceptedIntent.goal);
+  if (goal) {
+    return goal;
+  }
+  const found = [];
+  collectObjectiveStrings(result, found, 0);
+  if (found[0]) {
+    return found[0];
+  }
+  throwCopyStatus('Execution has no reconstructable start message', 422);
+}
+
+function lifecycleStateFromStatus(status) {
+  const token = String((status && status.status) || '').trim();
+  if (token === 'waiting') {
+    const wait = status.wait && typeof status.wait === 'object' ? status.wait : {};
+    if (String(wait.answerType || wait.waitReason || '') === 'approval') {
+      return 'approval-required';
+    }
+    return 'question';
+  }
+  return STATUS_LIFECYCLE[token] || null;
+}
+
+function resultProjectionExists(result) {
+  return Boolean(result && typeof result === 'object' && (result.completion || result.sourceCompleteness));
+}
+
+function ranCapabilityKeys(result) {
+  if (!result || typeof result !== 'object') {
+    return [];
+  }
+  const fromSteps = [];
+  const seen = new Set();
+  const steps = Array.isArray(result.steps) ? result.steps : [];
+  for (const step of steps) {
+    const block = step && step.capabilityExecution && typeof step.capabilityExecution === 'object'
+      ? step.capabilityExecution
+      : {};
+    const key = String(block.capabilityKey || '').trim();
+    if (key && !seen.has(key)) {
+      seen.add(key);
+      fromSteps.push(key);
+    }
+  }
+  if (fromSteps.length > 0) {
+    return fromSteps;
+  }
+  return collectObservedCapabilities({ steps: result.steps, workResult: result });
+}
+
+function buildCopyExpected(status, result) {
+  const expected = {};
+  const lifecycle = lifecycleStateFromStatus(status);
+  if (lifecycle) {
+    expected.lifecycleState = lifecycle;
+  }
+  if (resultProjectionExists(result)) {
+    expected.honesty = { requireWorkResult: true };
+  }
+  const required = ranCapabilityKeys(result);
+  if (required.length > 0) {
+    expected.capabilities = { required };
+  }
+  return expected;
+}
+
+module.exports = {
+  startMessageFromWorkReference,
+  buildCopyExpected
+};

package/lib/role-assistant/test-case-copy-from-work.js

@@ -0,0 +1,90 @@
+/**
+ * Build a Role Assistant test case from Work Hub status and result.
+ *
+ * @fileoverview CLI materializes 187 YAML; dataplane is the PE reference only
+ */
+
+'use strict';
+
+const {
+  getWorkExecutionStatus,
+  getWorkExecutionResult
+} = require('../api/work.api');
+const { throwCopyStatus, assertCopyBoundToSystem } = require('./test-case-copy-bind');
+const { mapCopyInteractions } = require('./test-case-copy-interactions');
+const {
+  startMessageFromWorkReference,
+  buildCopyExpected
+} = require('./test-case-copy-expected');
+
+function remapCopyReferenceError(error) {
+  const status = Number(error && error.status) || 0;
+  if (status === 404) {
+    throwCopyStatus('Execution was not found', 404);
+  }
+  if (status === 403) {
+    throwCopyStatus('Permission denied', 403);
+  }
+  throw error;
+}
+
+async function readWorkStatus(dataplaneUrl, authConfig, processExecutionId) {
+  try {
+    return await getWorkExecutionStatus(dataplaneUrl, authConfig, processExecutionId);
+  } catch (error) {
+    remapCopyReferenceError(error);
+  }
+  return null;
+}
+
+async function readWorkResult(dataplaneUrl, authConfig, processExecutionId) {
+  try {
+    return await getWorkExecutionResult(dataplaneUrl, authConfig, processExecutionId, {
+      requestedDepth: 'business',
+      format: 'json'
+    });
+  } catch (error) {
+    if (Number(error && error.status) === 404) {
+      return null;
+    }
+    remapCopyReferenceError(error);
+  }
+  return null;
+}
+
+async function fetchWorkCopyReference(dataplaneUrl, authConfig, processExecutionId) {
+  const status = await readWorkStatus(dataplaneUrl, authConfig, processExecutionId);
+  const result = await readWorkResult(dataplaneUrl, authConfig, processExecutionId);
+  return { status, result };
+}
+
+function omitEmptyList(doc, key, rows) {
+  if (Array.isArray(rows) && rows.length > 0) {
+    doc[key] = rows;
+  }
+}
+
+function buildCopyCaseFromWorkReference(args) {
+  const { systemKey, caseId, processExecutionId, status, result } = args;
+  const bind = assertCopyBoundToSystem(systemKey, status, result);
+  const message = startMessageFromWorkReference(result);
+  const mapped = mapCopyInteractions(result);
+  const warnings = [...mapped.warnings];
+  if (!bind.bound) {
+    warnings.push('Role Assistant identity was not on the execution reference');
+  }
+  const caseDoc = {
+    caseId,
+    input: { executionPath: 'workHub', message },
+    expected: buildCopyExpected(status, result),
+    metadata: { sourceProcessExecutionId: processExecutionId }
+  };
+  omitEmptyList(caseDoc, 'answers', mapped.answers);
+  omitEmptyList(caseDoc, 'approvals', mapped.approvals);
+  return { case: caseDoc, warnings };
+}
+
+module.exports = {
+  fetchWorkCopyReference,
+  buildCopyCaseFromWorkReference
+};

package/lib/role-assistant/test-case-copy-interactions.js

@@ -0,0 +1,67 @@
+/**
+ * Map work.result interactions onto 187 answers and approvals.
+ *
+ * @fileoverview Completed waits only; pending waits are omitted
+ */
+
+'use strict';
+
+const { throwCopyStatus } = require('./test-case-copy-bind');
+
+const ANSWERED = new Set(['answered', 'approved']);
+
+function asObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+
+function interactionValue(row) {
+  const response = asObject(row.response);
+  if (Object.prototype.hasOwnProperty.call(response, 'decision') && response.decision !== null
+    && response.decision !== undefined) {
+    return response.decision;
+  }
+  if (Object.prototype.hasOwnProperty.call(response, 'data')) {
+    return response.data;
+  }
+  return null;
+}
+
+function mapAnsweredInteraction(row, answers, approvals, warnings) {
+  const questionKey = String(row.questionKey || '').trim();
+  if (!questionKey) {
+    warnings.push('Skipped a completed interaction without a questionKey');
+    return;
+  }
+  const entry = { when: { questionKey }, value: interactionValue(row) };
+  if (String(row.interactionKind || '') === 'approval') {
+    approvals.push(entry);
+    return;
+  }
+  answers.push(entry);
+}
+
+function mapCopyInteractions(result) {
+  const rows = Array.isArray(result && result.interactions) ? result.interactions : [];
+  const answers = [];
+  const approvals = [];
+  const warnings = [];
+  let answeredCount = 0;
+  for (const row of rows) {
+    if (!row || typeof row !== 'object' || !ANSWERED.has(String(row.status || ''))) {
+      continue;
+    }
+    answeredCount += 1;
+    mapAnsweredInteraction(row, answers, approvals, warnings);
+  }
+  if (answeredCount > 0 && answers.length === 0 && approvals.length === 0) {
+    throwCopyStatus('Completed interactions could not be bound to questionKey', 422);
+  }
+  return { answers, approvals, warnings };
+}
+
+module.exports = {
+  mapCopyInteractions
+};

package/lib/role-assistant/test-case-copy.js

@@ -0,0 +1,119 @@
+/**
+ * Persist a copied Role Assistant test case as local YAML.
+ *
+ * @fileoverview UUID checks and AJV-gated write of a copied case document
+ */
+
+'use strict';
+
+const path = require('path');
+const yaml = require('js-yaml');
+const fs = require('../internal/fs-real-sync');
+const { YAML_SPEC_KEYS } = require('./test-pack-map');
+const { assertTestCaseDocument } = require('./test-case-validate');
+
+const PE_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const WORK_HUB_REF_MSG =
+  '--reference must be a Work Hub execution id (the same id printed after a run)';
+
+function normalizeProcessExecutionId(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^\{|\}$/g, '');
+}
+
+function defaultCaseIdFromReference(reference) {
+  const hex = normalizeProcessExecutionId(reference).replace(/-/g, '').toLowerCase();
+  return `copy-${hex.slice(0, 8)}`;
+}
+
+function assertProcessExecutionId(value) {
+  const id = normalizeProcessExecutionId(value);
+  if (!PE_UUID_RE.test(id)) {
+    throw new Error(WORK_HUB_REF_MSG);
+  }
+  return id.toLowerCase();
+}
+
+function assertFolderToken(value, label) {
+  const token = String(value || '').trim();
+  if (!token || token.includes('..') || /[/\\]/.test(token)) {
+    throw new Error(`${label} must be a folder name (for example 001)`);
+  }
+  return token;
+}
+
+function copyTargetPath(testsDir, suiteId, caseId) {
+  return path.join(testsDir, suiteId, `${caseId}.yaml`);
+}
+
+function extractCopyCase(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null;
+  }
+  if (payload.case && typeof payload.case === 'object' && !Array.isArray(payload.case)) {
+    return payload.case;
+  }
+  if (typeof payload.caseId === 'string' || payload.input) {
+    return payload;
+  }
+  return null;
+}
+
+function withCopyProvenance(doc, processExecutionId) {
+  return {
+    ...doc,
+    metadata: {
+      ...(doc.metadata && typeof doc.metadata === 'object' ? doc.metadata : {}),
+      sourceProcessExecutionId: processExecutionId
+    }
+  };
+}
+
+function pickYamlSpec(doc) {
+  const out = {};
+  for (const key of YAML_SPEC_KEYS) {
+    if (doc[key] !== undefined) {
+      out[key] = doc[key];
+    }
+  }
+  return out;
+}
+
+function prepareCopyDocument(payload, caseId, processExecutionId) {
+  const raw = extractCopyCase(payload);
+  if (!raw) {
+    throw new Error('Copy did not return a test case');
+  }
+  const doc = withCopyProvenance({ ...raw, caseId }, processExecutionId);
+  assertTestCaseDocument(doc, `${caseId}.yaml`);
+  return pickYamlSpec(doc);
+}
+
+function yamlFromValidatedCase(doc) {
+  return yaml.dump(doc, { lineWidth: 120, noRefs: true, sortKeys: false });
+}
+
+function assertCopyTargetWritable(targetPath, force) {
+  if (fs.existsSync(targetPath) && force !== true) {
+    throw new Error('Test case already exists. Pass --force to overwrite.');
+  }
+}
+
+function persistCopyCaseYaml(targetPath, yamlText) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, yamlText, 'utf8');
+}
+
+module.exports = {
+  WORK_HUB_REF_MSG,
+  defaultCaseIdFromReference,
+  assertProcessExecutionId,
+  assertFolderToken,
+  copyTargetPath,
+  extractCopyCase,
+  prepareCopyDocument,
+  yamlFromValidatedCase,
+  assertCopyTargetWritable,
+  persistCopyCaseYaml
+};