@aifabrix/builder 2.54.1 → 2.55.0

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
+};

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

@@ -0,0 +1,135 @@
+/**
+ * Nested expected-field catalog for Role Assistant YAML cases.
+ * @fileoverview Fail-closed coverage walk after AJV nested schema
+ */
+
+'use strict';
+
+const HONESTY_KEYS = [
+  'requireWorkResult',
+  'schemaVersion',
+  'requireCompletion',
+  'requireContributionObservation',
+  'minResourceChanges',
+  'softResourceChanges',
+  'forbidBuilderKeysInObjective'
+];
+const SEARCH_KEYS = [
+  'statusCode',
+  'operation',
+  'resultMode',
+  'minRows',
+  'errorContains',
+  'graphDepth',
+  'relatedTypes',
+  'related'
+];
+const SEARCH_RELATED_KEYS = ['minRows', 'resultMode'];
+const SKILLS_KEYS = ['resourceType', 'operations', 'filterFields', 'operationRequired'];
+const EVIDENCE_KEYS = ['requiredKeys', 'roleKey', 'resourceType', 'requireStatus'];
+const BID_KEYS = [
+  'schemaName',
+  'schemaVersion',
+  'requireDefinitionHash',
+  'requireSuiteRunId',
+  'forbidGoldPaths',
+  'minDatasources',
+  'requireCapability'
+];
+const EXPECTED_KEYS = [
+  'soft',
+  'softNotes',
+  'honesty',
+  'lifecycleState',
+  'capabilities',
+  'search',
+  'skills',
+  'evidence',
+  'bid',
+  'facts',
+  'prohibited'
+];
+const CAPABILITY_KEYS = ['allowed', 'required', 'forbidden'];
+const NESTED = {
+  'expected.honesty': HONESTY_KEYS,
+  'expected.search': SEARCH_KEYS,
+  'expected.skills': SKILLS_KEYS,
+  'expected.evidence': EVIDENCE_KEYS,
+  'expected.bid': BID_KEYS,
+  'expected.capabilities': CAPABILITY_KEYS,
+  'preflight.evidence': EVIDENCE_KEYS
+};
+
+function objectKeys(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return [];
+  }
+  return Object.keys(value);
+}
+
+function unknownKeyError(filePath, pointer, key, allowed) {
+  const allowedText = allowed.join(', ');
+  return (
+    `${filePath}: unknown field ${pointer}.${key}. ` +
+    `Allowed properties: ${allowedText}. ` +
+    'Remove the field or rename it to a listed property.'
+  );
+}
+
+function collectUnknownInObject(filePath, pointer, value, allowed, errors) {
+  for (const key of objectKeys(value)) {
+    if (!allowed.includes(key)) {
+      errors.push(unknownKeyError(filePath, pointer, key, allowed));
+    }
+  }
+}
+
+function collectSearchRelatedUnknown(filePath, related, errors) {
+  for (const resourceType of objectKeys(related)) {
+    collectUnknownInObject(
+      filePath,
+      `expected.search.related.${resourceType}`,
+      related[resourceType],
+      SEARCH_RELATED_KEYS,
+      errors
+    );
+  }
+}
+
+function collectNestedUnknown(filePath, parsed, errors) {
+  const expected = parsed.expected && typeof parsed.expected === 'object' ? parsed.expected : {};
+  collectUnknownInObject(filePath, 'expected', expected, EXPECTED_KEYS, errors);
+  collectUnknownInObject(filePath, 'expected.honesty', expected.honesty, HONESTY_KEYS, errors);
+  collectUnknownInObject(filePath, 'expected.search', expected.search, SEARCH_KEYS, errors);
+  collectSearchRelatedUnknown(filePath, expected.search && expected.search.related, errors);
+  collectUnknownInObject(filePath, 'expected.skills', expected.skills, SKILLS_KEYS, errors);
+  collectUnknownInObject(filePath, 'expected.evidence', expected.evidence, EVIDENCE_KEYS, errors);
+  collectUnknownInObject(filePath, 'expected.bid', expected.bid, BID_KEYS, errors);
+  collectUnknownInObject(
+    filePath,
+    'expected.capabilities',
+    expected.capabilities,
+    CAPABILITY_KEYS,
+    errors
+  );
+  const preflight = parsed.preflight && typeof parsed.preflight === 'object' ? parsed.preflight : {};
+  collectUnknownInObject(filePath, 'preflight.evidence', preflight.evidence, EVIDENCE_KEYS, errors);
+}
+
+function assertExpectedCoverage(parsed, filePath) {
+  const errors = [];
+  collectNestedUnknown(filePath, parsed || {}, errors);
+  return errors;
+}
+
+module.exports = {
+  HONESTY_KEYS,
+  SEARCH_KEYS,
+  SEARCH_RELATED_KEYS,
+  SKILLS_KEYS,
+  EVIDENCE_KEYS,
+  BID_KEYS,
+  EXPECTED_KEYS,
+  NESTED,
+  assertExpectedCoverage
+};

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

@@ -0,0 +1,88 @@
+/**
+ * Offline Role Assistant test-case schema validation.
+ * @fileoverview AJV check for YAML cases before auth or package publish
+ */
+
+'use strict';
+
+const path = require('path');
+const { parseJsonFileContent } = require('../validation/validate-external-file');
+const { loadRoleAssistantTestCaseSchema } = require('../utils/schema-loader');
+const { formatValidationErrors } = require('../utils/error-formatter');
+const { assertExpectedCoverage } = require('./test-case-expected-catalog');
+
+const TEST_CASE_TYPE = 'role-assistant-test-case';
+
+function formatCaseErrors(filePath, ajvErrors) {
+  return formatValidationErrors(ajvErrors, { dedupe: true }).map((msg) => {
+    const fix = /additional properties/i.test(msg)
+      ? ' Remove the field or rename it to a listed property.'
+      : '';
+    return `${filePath}: ${msg}${fix}`;
+  });
+}
+
+function validateTestCaseDocument(parsed, filePath) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      valid: false,
+      errors: [`${filePath}: Test case must be an object`],
+      warnings: []
+    };
+  }
+  const validate = loadRoleAssistantTestCaseSchema();
+  const ok = validate(parsed);
+  const errors = ok
+    ? assertExpectedCoverage(parsed, filePath)
+    : formatCaseErrors(filePath, validate.errors);
+  return { valid: errors.length === 0, errors, warnings: [] };
+}
+
+function validateTestCaseFile(filePath) {
+  const parseResult = parseJsonFileContent(filePath);
+  if (parseResult.error) {
+    return { ...parseResult.error, file: filePath, type: TEST_CASE_TYPE };
+  }
+  const result = validateTestCaseDocument(parseResult.parsed, filePath);
+  return { ...result, file: filePath, type: TEST_CASE_TYPE };
+}
+
+function assertTestCaseDocument(parsed, filePath) {
+  const result = validateTestCaseDocument(parsed, filePath);
+  if (!result.valid) {
+    throw new Error(result.errors.join('\n'));
+  }
+}
+
+function throwIfCaseFileInvalid(filePath) {
+  const result = validateTestCaseFile(filePath);
+  if (!result.valid) {
+    throw new Error(result.errors.join('\n'));
+  }
+}
+
+function assertLocalCasesBeforeAuth(systemKey, opts) {
+  if (!opts || opts.fromDataplane || opts.listCases) {
+    return;
+  }
+  const { listTestCaseFiles, loadRoleAssistantTestCase } = require('./test-cases');
+  if (opts.case) {
+    loadRoleAssistantTestCase(systemKey, opts.case, { testsDir: opts.testsDir || null });
+    return;
+  }
+  if (!opts.suite) {
+    return;
+  }
+  const testsDir = opts.testsDir || path.join(process.cwd(), 'role-assistant', systemKey, 'tests');
+  for (const filePath of listTestCaseFiles(testsDir)) {
+    throwIfCaseFileInvalid(filePath);
+  }
+}
+
+module.exports = {
+  TEST_CASE_TYPE,
+  validateTestCaseDocument,
+  validateTestCaseFile,
+  assertTestCaseDocument,
+  assertLocalCasesBeforeAuth
+};