@aifabrix/builder 2.59.0 → 2.61.2

package/lib/datasource/capability/upsert-test-scaffold.js

@@ -0,0 +1,189 @@
+/**
+ * Build a no-duplicate upsert proof from author-owned scenario facts.
+ *
+ * @fileoverview Safe testPayload scaffolding for datasource capability upsert
+ */
+
+'use strict';
+
+const { deepClone } = require('./copy-operations');
+
+const RUN_TOKEN = /\{\{\s*testRunId\s*\}\}/i;
+
+function scenarioInput(scenario) {
+  const input = scenario?.input;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const properties = input.properties;
+  return properties && typeof properties === 'object' && !Array.isArray(properties)
+    ? properties
+    : input;
+}
+
+function scalar(value) {
+  return value !== null && ['string', 'number', 'boolean'].includes(typeof value);
+}
+
+function identityFromInput(input, identityFields) {
+  if (!input) return null;
+  const entries = identityFields.map((field) => [field, input[field]]);
+  if (entries.some(([, value]) => !scalar(value) || value === '')) return null;
+  return Object.fromEntries(entries);
+}
+
+function sameIdentity(first, second, identityFields) {
+  return identityFields.every((field) => first[field] === second[field]);
+}
+
+function isCollisionSafe(identity) {
+  return Object.values(identity).some((value) =>
+    typeof value === 'string' && RUN_TOKEN.test(value)
+  );
+}
+
+function profileFields(doc, targetKey) {
+  const profile = doc.exposed?.profiles?.[targetKey];
+  if (Array.isArray(profile)) return profile;
+  return Array.isArray(profile?.attributes) ? profile.attributes : [];
+}
+
+function changedPublishedField(doc, targetKey, first, second, identityFields) {
+  const identity = new Set(identityFields);
+  const published = new Set(profileFields(doc, targetKey));
+  return Object.keys(first).find((field) =>
+    !identity.has(field) && published.has(field) && scalar(first[field]) &&
+    scalar(second[field]) && first[field] !== second[field]
+  ) || null;
+}
+
+function analyzeWritePair(doc, targetKey, identityFields, firstRow, secondRow) {
+  const first = scenarioInput(firstRow);
+  const second = scenarioInput(secondRow);
+  const firstIdentity = identityFromInput(first, identityFields);
+  const secondIdentity = identityFromInput(second, identityFields);
+  if (!firstIdentity || !secondIdentity) return { reason: 'both writes must contain every business identity field' };
+  if (!sameIdentity(firstIdentity, secondIdentity, identityFields)) {
+    return { reason: 'the two writes must use the same business identity values' };
+  }
+  if (!isCollisionSafe(firstIdentity)) {
+    return { reason: 'the business identity must include {{testRunId}} to isolate each live run' };
+  }
+  const changedField = changedPublishedField(
+    doc, targetKey, first, second, identityFields
+  );
+  if (!changedField) {
+    return { reason: 'the second write must change one published non-identity scalar field' };
+  }
+  return { first, second, identity: firstIdentity, changedField };
+}
+
+function exactLookup(operation, input, expectedRows, identityKey) {
+  return {
+    operation,
+    input: deepClone(input),
+    identityKey,
+    matchMode: 'exactIdentities',
+    expectedRows: deepClone(expectedRows)
+  };
+}
+
+function expectedRow(identity, changedField, value) {
+  return { ...deepClone(identity), [changedField]: value };
+}
+
+function hasExactProof(scenarios, index, targetKey, lookupKey, facts) {
+  const rows = scenarios.slice(index, index + 5);
+  if (rows.length !== 5) return false;
+  const operations = rows.map((row) => row?.operation);
+  if (operations.join('|') !== [lookupKey, targetKey, lookupKey, targetKey, lookupKey].join('|')) {
+    return false;
+  }
+  const [before, , afterFirst, , afterSecond] = rows;
+  return [before, afterFirst, afterSecond].every((row) =>
+    row?.matchMode === 'exactIdentities' && row?.identityKey === facts.changedField
+  ) && Array.isArray(before.expectedRows) && before.expectedRows.length === 0 &&
+    afterFirst.expectedRows?.length === 1 && afterSecond.expectedRows?.length === 1 &&
+    afterFirst.expectedRows?.[0]?.[facts.changedField] === facts.first[facts.changedField] &&
+    afterSecond.expectedRows?.[0]?.[facts.changedField] === facts.second[facts.changedField];
+}
+
+function findExistingProof(doc, scenarios, targetKey, lookupKey, identityFields) {
+  for (let index = 0; index <= scenarios.length - 5; index += 1) {
+    const facts = analyzeWritePair(
+      doc, targetKey, identityFields, scenarios[index + 1], scenarios[index + 3]
+    );
+    if (!facts.reason && hasExactProof(scenarios, index, targetKey, lookupKey, facts)) return true;
+  }
+  return false;
+}
+
+function findAdjacentWrites(doc, scenarios, targetKey, identityFields) {
+  let lastReason = 'two adjacent enabled upsert scenarios are required';
+  for (let index = 0; index < scenarios.length - 1; index += 1) {
+    const first = scenarios[index];
+    const second = scenarios[index + 1];
+    if (first?.operation !== targetKey || second?.operation !== targetKey) continue;
+    if (first.enabled === false || second.enabled === false) continue;
+    const facts = analyzeWritePair(doc, targetKey, identityFields, first, second);
+    if (!facts.reason) return { index, facts };
+    lastReason = facts.reason;
+  }
+  return { reason: lastReason };
+}
+
+function insufficientIssue(reason) {
+  return {
+    code: 'UPSERT-TEST-DATA-INSUFFICIENT',
+    severity: 'blocking',
+    ownership: 'test-payload',
+    aiFixable: false,
+    message: `Safe --test scaffolding was not generated: ${reason}; no values were fabricated`,
+    consequence: 'A weaker generated case could provide false no-duplicate confidence.',
+    remediation: ['Author two adjacent upsert inputs with the same isolated identity and one changed published field, then rerun --test.'],
+    prevention: 'Keep collision-safe two-write facts with the datasource test payload.',
+    residualRisk: 'Upsert remains unproven until the exact live chain passes.'
+  };
+}
+
+function buildProofRows(lookupKey, facts) {
+  const firstExpected = expectedRow(
+    facts.identity, facts.changedField, facts.first[facts.changedField]
+  );
+  const secondExpected = expectedRow(
+    facts.identity, facts.changedField, facts.second[facts.changedField]
+  );
+  return [
+    exactLookup(lookupKey, facts.identity, [], facts.changedField),
+    exactLookup(lookupKey, facts.identity, [firstExpected], facts.changedField),
+    exactLookup(lookupKey, facts.identity, [secondExpected], facts.changedField)
+  ];
+}
+
+function scaffoldUpsertTests(originalDoc, analysis, targetKey = 'upsert') {
+  const scenarios = originalDoc.testPayload?.scenarios;
+  const lookupKey = analysis?.selectedLookup?.operationKey;
+  const identities = Array.isArray(analysis?.identityFields) ? analysis.identityFields : [];
+  if (!Array.isArray(scenarios) || !lookupKey || identities.length === 0) {
+    return { changed: false, issue: insufficientIssue('required scenarios or exact lookup facts are missing') };
+  }
+  if (findExistingProof(originalDoc, scenarios, targetKey, lookupKey, identities)) {
+    return { changed: false, doc: originalDoc, patchOperations: [], updatedSections: [] };
+  }
+  const pair = findAdjacentWrites(originalDoc, scenarios, targetKey, identities);
+  if (pair.reason) return { changed: false, issue: insufficientIssue(pair.reason) };
+  const [before, afterFirst, afterSecond] = buildProofRows(lookupKey, pair.facts);
+  const doc = deepClone(originalDoc);
+  doc.testPayload.scenarios.splice(pair.index, 2,
+    before, scenarios[pair.index], afterFirst, scenarios[pair.index + 1], afterSecond);
+  return {
+    changed: true,
+    doc,
+    patchOperations: [{ op: 'replace', path: '/testPayload/scenarios', value: doc.testPayload.scenarios }],
+    updatedSections: ['testPayload.scenarios: upsert no-duplicate proof']
+  };
+}
+
+module.exports = {
+  scaffoldUpsertTests,
+  analyzeWritePair,
+  insufficientIssue
+};

package/lib/datasource/validate.js

@@ -23,6 +23,8 @@ const { validateFieldReferences } = require('./field-reference-validator');
 const { validateAbac } = require('./abac-validator');
 const { buildDatasourceValidateSummary } = require('./datasource-validate-summary');
 
+const { validateBinaryDocumentsContract } = require('./binary-documents-validator');
+
 const DATASOURCE_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 const EXCLUDE_CONFIG_NAMES = new Set([
   'application.json',
@@ -242,12 +244,14 @@ async function validateDatasourceFile(filePathOrKey) {
     };
   }
 
+  const binary = validateBinaryDocumentsContract(parsed);
+  const warnings = binary.warnings.map(issue => `${issue.code}: ${issue.message}`);
   const postSchemaErrors = collectPostSchemaErrors(parsed);
   if (postSchemaErrors.length > 0) {
     return {
       valid: false,
       errors: postSchemaErrors,
-      warnings: [],
+      warnings,
       resolvedPath: filePath,
       summary
     };
@@ -256,7 +260,7 @@ async function validateDatasourceFile(filePathOrKey) {
   return {
     valid: true,
     errors: [],
-    warnings: [],
+    warnings,
     resolvedPath: filePath,
     summary
   };
@@ -269,7 +273,8 @@ async function validateDatasourceFile(filePathOrKey) {
 function collectPostSchemaErrors(parsed) {
   return [
     ...validateFieldReferences(parsed),
-    ...validateAbac(parsed)
+    ...validateAbac(parsed),
+    ...validateBinaryDocumentsContract(parsed).errors.map(issue => `${issue.code}: ${issue.message}`)
   ];
 }
 
@@ -303,12 +308,14 @@ function validateDatasourceParsed(parsed) {
     };
   }
 
+  const binary = validateBinaryDocumentsContract(parsed);
+  const warnings = binary.warnings.map(issue => `${issue.code}: ${issue.message}`);
   const postSchemaErrors = collectPostSchemaErrors(parsed);
   if (postSchemaErrors.length > 0) {
     return {
       valid: false,
       errors: postSchemaErrors,
-      warnings: [],
+      warnings,
       summary
     };
   }
@@ -316,7 +323,7 @@ function validateDatasourceParsed(parsed) {
   return {
     valid: true,
     errors: [],
-    warnings: [],
+    warnings,
     summary
   };
 }

package/lib/deployment/installation/azure-infra-stage.js

@@ -24,7 +24,9 @@ const preflight = require('./azure-preflight');
 const readiness = require('./azure-readiness');
 const registryAuth = require('./registry-auth-mode');
 
-const INFRA_SECRETS = Object.freeze(['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY']);
+// The Marketplace template stopped accepting moriCallbackApiKey: the installation receives its
+// Mori key at licence registration instead, so infra no longer provisions or projects one.
+const INFRA_SECRETS = Object.freeze(['ADMIN_PASSWORD', 'ENCRYPTION_KEY']);
 
 function missingInputError(file, fields) {
   const error = new Error(

package/lib/deployment/installation/infra-catalog.js

@@ -100,8 +100,6 @@ const PARAMETER_CATALOG = Object.freeze({
   moriBaseUrl: { kind: 'file', source: 'registration', required: true, description: 'Mori service base URL.' },
   moriLicensePublicKey: { kind: 'file', source: 'registration', required: false, description: 'Mori licence issuer public key (SPKI PEM); empty leaves the installation unpinned and it then refuses every licence.' },
   moriLicenseIssuer: { kind: 'file', source: 'registration', required: false, description: 'Expected iss claim on a Mori licence.' },
-  moriCallbackApiKey: { kind: 'secretEnv', env: 'MORI_CALLBACK_API_KEY', required: true, description: 'Mori callback authentication key.' },
-  entraCallbackStateSecret: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdClientId: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdClientSecret: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdTenantId: { kind: 'deferred', description: 'Customer Entra provider tenant; distinct from the Azure subscription directory tenant and configured later.' },
@@ -146,14 +144,13 @@ const MORI_SERVICE_KEY = 'mori-controller-api-keyKeyVault';
 const SECRET_BINDINGS = Object.freeze({
   ADMIN_PASSWORD: { kv: 'miso-controller-admin-passwordKeyVault', required: true, generate: false, comment: 'Required installation administrator password; same canonical secret used by Miso onboarding.' },
   ENCRYPTION_KEY: { kv: 'miso-controller-secrets-encryptionKeyVault', required: true, generate: true, comment: 'Application/data encryption key.' },
-  MORI_CALLBACK_API_KEY: { kv: 'mori-callback-api-keyKeyVault', required: true, generate: true, comment: 'Mori callback credential.' },
   MISO_API_KEY: { kv: 'miso-controller-secrets-apiKeyVault', required: false, generate: false, comment: 'Temporary Miso deployment key; an existing login may be used instead.' },
   MORI_API_KEY: { kv: MORI_SERVICE_KEY, required: true, generate: false, comment: 'Mori installation service key stored by DOCKER registration.' }
 });
 
 const ENV_TEMPLATE_KEYS = Object.freeze({
-  AZURE: ['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY', 'MISO_API_KEY'],
-  DOCKER: ['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY', 'MORI_API_KEY']
+  AZURE: ['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MISO_API_KEY'],
+  DOCKER: ['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_API_KEY']
 });
 
 /**

package/lib/generator/builders.js

@@ -362,6 +362,23 @@ function addSimpleOptionalFields(deployment, variables) {
   if (variables.required !== undefined && !(Array.isArray(variables.required) && variables.required.length === 0)) {
     deployment.required = variables.required;
   }
+  addPlatformSections(deployment, variables);
+}
+
+/**
+ * Carries the platform/environment declarations into the deployment manifest so the Controller can
+ * resolve `{NAME}` values per installation, which is the case Builder cannot resolve: one uploaded
+ * application serving many customer resource groups.
+ * @param {Object} deployment - Deployment manifest (mutated)
+ * @param {Object} variables - Application manifest
+ */
+function addPlatformSections(deployment, variables) {
+  if (Array.isArray(variables.platforms) && variables.platforms.length > 0) {
+    deployment.platforms = variables.platforms;
+  }
+  if (Array.isArray(variables.environments) && variables.environments.length > 0) {
+    deployment.environments = variables.environments;
+  }
 }
 
 function buildOptionalFields(deployment, variables, rbac) {

package/lib/generator/helpers.js

@@ -243,6 +243,27 @@ function determineVariableLocation(value) {
   return value.startsWith('kv://') ? 'keyvault' : 'variable';
 }
 
+/**
+ * Expands manifest `{NAME}` values into the env template before it becomes configuration items.
+ * Lenient by design: with no deployment target the tokens stay in the manifest for the Controller
+ * to resolve per installation, which is what the SaaS case needs. A known target resolves fully.
+ * @param {string} envTemplate - Raw env template
+ * @param {Object|null} variablesConfig - Application manifest
+ * @param {Object|null} target - `environment` and `resourceGroup` when known
+ * @returns {string}
+ */
+function expandManifestNames(envTemplate, variablesConfig, target) {
+  const { expandPlatformNamesIfPresent } = require('../core/env-platform-expand');
+  const known = target && (target.resourceGroup || target.environment);
+  if (!known) return envTemplate;
+  return expandPlatformNamesIfPresent(envTemplate, {
+    manifest: variablesConfig,
+    environment: target.environment,
+    resourceGroup: target.resourceGroup,
+    strict: Boolean(target.resourceGroup)
+  });
+}
+
 /**
  * Creates a configuration item from parsed variable
  * @function createConfigItem
@@ -282,9 +303,9 @@ function createConfigItem(key, value, location, applicationConfigMap) {
   return configItem;
 }
 
-function parseEnvironmentVariables(envTemplate, variablesConfig = null) {
+function parseEnvironmentVariables(envTemplate, variablesConfig = null, target = null) {
   const configuration = [];
-  const lines = envTemplate.split('\n');
+  const lines = expandManifestNames(envTemplate, variablesConfig, target).split('\n');
   const applicationConfigMap = createApplicationConfigMap(variablesConfig);
   for (const line of lines) {
     const parsed = parseEnvironmentVariableLine(line);

package/lib/generator/index.js

@@ -22,6 +22,7 @@ const { generateControllerManifest } = require('./external-controller-manifest')
 const { resolveVersionForApp } = require('../utils/image-version');
 const { getContainerPort } = require('../utils/port-resolver');
 const { buildEnvVarMap } = require('../utils/env-map');
+const { mergeAdditionalPublishedPorts } = require('../utils/docker-manifest-public-port');
 
 /**
  * Generates deployment JSON from application configuration files
@@ -175,8 +176,9 @@ function substituteEnvVarsInDeployment(obj, envVarMap, fieldPath = '') {
  * @throws {Error} If validation fails
  */
 function buildAndValidateDeployment(appName, variables, envTemplate, rbac, options = null) {
-  // Parse environment variables from template and merge portalInput from application config
-  const configuration = parseEnvironmentVariables(envTemplate, variables);
+  // Parse environment variables from template and merge portalInput from application config.
+  // A known deployment target resolves manifest {NAME} values; otherwise they stay for the Controller.
+  const configuration = parseEnvironmentVariables(envTemplate, variables, options && options.target);
 
   // Build deployment manifest (Controller computes deploymentKey from schema)
   const deployment = builders.buildManifestStructure(appName, variables, configuration, rbac);
@@ -236,7 +238,7 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
     ...variables,
     app: { ...variables.app, version: resolved.version }
   };
-  const configuration = parseEnvironmentVariables(envTemplate, variables);
+  const configuration = parseEnvironmentVariables(envTemplate, variables, options && options.target);
   const deployment = builders.buildManifestStructure(appName, variablesWithVersion, configuration, rbac);
 
   const effectivePort = getEffectivePortForSubstitution(variablesWithVersion, 3000);
@@ -246,6 +248,7 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
       ? parseInt(deployment.port, 10) : (typeof deployment.port === 'number' ? deployment.port : effectivePort);
   }
   const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
+  await mergeAdditionalPublishedPorts(envVarMap, variablesWithVersion);
   substituteEnvVarsInDeployment(deployment, envVarMap);
   _validator.validateNoUnresolvedVariablesInDeployment(deployment);
   return { deployment, appPath };
@@ -290,7 +293,7 @@ async function writeExternalDeployJson(appName, appPath, options) {
  * @param {string} appType - Application type
  * @returns {Promise<string>} Path to written deploy JSON
  */
-async function writeRegularDeployJson(appName, appPath, appType) {
+async function writeRegularDeployJson(appName, appPath, appType, options = {}) {
   const { variables, envTemplate, rbac, jsonPath } = loadDeploymentConfigFiles(appPath, appType, appName);
   const resolved = await resolveVersionForApp(appName, variables, { updateBuilder: false });
   const variablesWithVersion = {
@@ -299,7 +302,11 @@ async function writeRegularDeployJson(appName, appPath, appType) {
   };
   const effectivePort = getEffectivePortForSubstitution(variablesWithVersion, 3000);
   const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
-  const deployment = buildAndValidateDeployment(appName, variablesWithVersion, envTemplate, rbac, { envVarMap });
+  await mergeAdditionalPublishedPorts(envVarMap, variablesWithVersion);
+  const deployment = buildAndValidateDeployment(appName, variablesWithVersion, envTemplate, rbac, {
+    envVarMap,
+    target: options.target
+  });
   const jsonContent = JSON.stringify(deployment, null, 2);
   fs.writeFileSync(jsonPath, jsonContent, { mode: 0o644 });
   return jsonPath;
@@ -333,7 +340,7 @@ async function generateDeployJson(appName, options = {}) {
   if (isExternal) {
     return writeExternalDeployJson(appName, appPath, options);
   }
-  return await writeRegularDeployJson(appName, appPath, appType);
+  return await writeRegularDeployJson(appName, appPath, appType, options);
 }
 
 async function generateDeployJsonWithValidation(appName, options = {}) {

package/lib/lifecycle/product-model.js

@@ -134,6 +134,7 @@ function computeOperationalReadinessPercent(checks) {
   let earned = 0;
   let total = 0;
   for (const [key, weight] of Object.entries(OPERATIONS_WEIGHTS)) {
+    if (checks[key] === null) continue;
     total += weight;
     if (checks[key] === true) {
       earned += weight;
@@ -159,9 +160,9 @@ function buildOperationsChecksFromSteps(steps) {
     authorization: integration || e2e,
     openApi: validation,
     mappings: validation,
-    sync: e2e,
-    crud: e2e,
-    execution: e2e,
+    sync: steps.keyedDocumentGet === true ? null : e2e,
+    crud: steps.keyedDocumentGet === true ? steps.documentPersistence === true : e2e,
+    execution: steps.keyedDocumentGet === true ? steps.documentPersistence === true : e2e,
     validation,
     unitTests: unit,
     integrationTests: integration,

package/lib/lifecycle/report-display.js

@@ -132,8 +132,9 @@ function displayOperationsVerificationSteps(detailsGrouped) {
   for (const [groupName, keys] of groups) {
     logger.log(chalk.white(groupName));
     for (const key of keys) {
-      const passed = detailsGrouped[groupName.toLowerCase()]?.[key] ?? detailsGrouped[key];
-      const glyph = passed ? successGlyph() : failureGlyph();
+      const group = detailsGrouped[groupName.toLowerCase()];
+      const passed = group && Object.hasOwn(group, key) ? group[key] : detailsGrouped[key];
+      const glyph = passed === null ? chalk.gray('⏭ Not applicable') : passed ? successGlyph() : failureGlyph();
       logger.log(`  ${labels[key] || key}`.padEnd(24) + glyph);
     }
   }

package/lib/parameters/infra-parameter-catalog.js

@@ -135,7 +135,7 @@ function createCatalogApi(doc, exact, patterns) {
     const entry = findEntryForKey(key);
     const gen = entry && entry.generator;
     // emptyAllowed: e.g. Redis password when no requirepass.
-    // emptyString: optional user-supplied keys (OpenAI / Azure OpenAI) — absent resolves like ''.
+    // emptyString: optional user-supplied catalog keys — absent resolves like ''.
     return Boolean(gen && (gen.type === 'emptyAllowed' || gen.type === 'emptyString'));
   }
 

package/lib/programmatic/builder-help-enterprise-sync-fabrix.js

@@ -10,7 +10,7 @@ const fs = require('fs');
 const path = require('path');
 const { buildHelpEnvelope } = require('./builder-help-envelope');
 
-const HELP_MD_DIR = path.join(__dirname, 'help-content');
+const HELP_MD_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help', 'content');
 
 /** @type {ReadonlyArray<string>} */
 const REPAIR_COMMANDS = Object.freeze([

package/lib/programmatic/builder-help-governance.js

@@ -15,7 +15,7 @@ const { listPlatformRoles } = require('./platform-rbac-catalog');
 const { CHANNEL_TARGET_KEYS, CHANNEL_TARGETS } = require('../channels/channel-targets');
 
 const BUILDER_HELP_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help');
-const HELP_MD_DIR = path.join(__dirname, 'help-content');
+const HELP_MD_DIR = path.join(BUILDER_HELP_DIR, 'content');
 
 /**
  * @param {string} fileName

package/lib/programmatic/builder-help.js

@@ -65,7 +65,7 @@ const PROSE_TOPIC_FILES = Object.freeze({
   enterpriseSyncFabrix: 'enterprise-sync-fabrix.md'
 });
 
-const HELP_MD_DIR = path.join(__dirname, 'help-content');
+const HELP_MD_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help', 'content');
 
 /**
  * @param {string} message

package/lib/role-assistant/test-cases-search.js

@@ -142,6 +142,9 @@ function evaluateSearchExpectations(expectedSearch, observation) {
 
 function skillsResourceEntry(skillsPayload, resourceType) {
   const root = skillsEnvelope(skillsPayload) || asObject(skillsPayload);
+  if (String(root.resourceType || '').trim() === resourceType) {
+    return root;
+  }
   const rts = asObject(asObject(root).search).resourceTypes;
   return asObject(asObject(rts)[resourceType]);
 }

package/lib/role-assistant/test-job-runner.js

@@ -0,0 +1,125 @@
+/**
+ * Run one published Role Assistant case as an explicitly selected subject.
+ *
+ * @fileoverview Async test-job isolation for the Role Assistant CLI
+ */
+
+'use strict';
+
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveUserIdOrEmail } = require('../identity/resolve-user-id');
+const {
+  enqueueRoleAssistantTestJob,
+  getRoleAssistantTestJob
+} = require('../api/role-assistant-test-job.api');
+const { roleAssistantSystemKey } = require('../utils/role-assistant-paths');
+
+function selectedSubject(opts) {
+  const ids = Array.isArray(opts.subjectUserId)
+    ? opts.subjectUserId.map((value) => String(value || '').trim()).filter(Boolean)
+    : [];
+  const emails = Array.isArray(opts.subjectEmail)
+    ? opts.subjectEmail.map((value) => String(value || '').trim()).filter(Boolean)
+    : [];
+  if (ids.length + emails.length > 1) {
+    throw new Error('Role Assistant case execution accepts exactly one isolation subject.');
+  }
+  return { userId: ids[0] || '', email: emails[0] || '' };
+}
+
+function hasRoleAssistantTestSubject(opts) {
+  const subject = selectedSubject(opts);
+  return Boolean(subject.userId || subject.email);
+}
+
+async function resolveSubjectUserId(opts, authConfig) {
+  const subject = selectedSubject(opts);
+  if (subject.userId) {
+    return subject.userId;
+  }
+  const controllerUrl = await resolveControllerUrl();
+  return resolveUserIdOrEmail(controllerUrl, authConfig, subject.email);
+}
+
+function waitFor(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function pollJob(roleKey, authContext, jobId, opts) {
+  const timeoutMs = Number(opts.pollTimeoutMs) || 180000;
+  const intervalMs = Number(opts.pollIntervalMs) || 750;
+  const startedAt = Date.now();
+  let job = null;
+  while (Date.now() - startedAt < timeoutMs) {
+    job = await getRoleAssistantTestJob(
+      authContext.dataplaneUrl,
+      authContext.authConfig,
+      roleAssistantSystemKey(roleKey),
+      jobId
+    );
+    const status = String(job?.status || '').trim().toLowerCase();
+    if (['completed', 'failed', 'cancelled'].includes(status)) {
+      return job;
+    }
+    await waitFor(intervalMs);
+  }
+  throw new Error(`Role Assistant test job ${jobId} did not finish within ${timeoutMs} ms.`);
+}
+
+function evaluationFromJobCase(roleCase, job, row, fallbackJobId = null) {
+  const assertions = Array.isArray(row?.assertions)
+    ? row.assertions.map((assertion) => ({
+      ...assertion,
+      passed: String(assertion?.kind || '').toLowerCase() !== 'fail'
+    }))
+    : [];
+  return {
+    caseId: row?.caseId || roleCase.caseId,
+    sourceFile: roleCase.sourceFile || null,
+    passed: row?.passed === true,
+    lifecycleState: row?.lifecycleState || String(job?.status || 'failed'),
+    assertions,
+    failedAssertions: assertions.filter((assertion) => assertion.passed === false),
+    warnings: assertions.filter((assertion) => assertion.kind === 'warn'),
+    execution: {
+      processExecutionId: row?.processExecutionId || null,
+      finalStatus: row?.lifecycleState || job?.status || null,
+      waitReason: null,
+      interactions: [],
+      workResultError: job?.errorMessage || null,
+      testJobId: job?.jobId || job?.id || fallbackJobId || null
+    }
+  };
+}
+
+async function runPublishedCaseAsSubject(roleKey, roleCase, opts, authContext) {
+  const subjectUserId = await resolveSubjectUserId(opts, authContext.authConfig);
+  const accepted = await enqueueRoleAssistantTestJob(
+    authContext.dataplaneUrl,
+    authContext.authConfig,
+    roleAssistantSystemKey(roleKey),
+    { caseId: roleCase.caseId, subjectUserId }
+  );
+  const jobId = String(accepted?.jobId || '').trim();
+  if (!jobId) {
+    throw new Error('Role Assistant test job enqueue did not return jobId.');
+  }
+  const job = await pollJob(roleKey, authContext, jobId, opts);
+  const row = Array.isArray(job?.cases)
+    ? job.cases.find((candidate) => candidate?.caseId === roleCase.caseId)
+    : null;
+  if (!row) {
+    throw new Error(
+      job?.errorMessage ||
+        `Published Role Assistant case '${roleCase.caseId}' returned no result in job ${jobId}.`
+    );
+  }
+  return evaluationFromJobCase(roleCase, job, row, jobId);
+}
+
+module.exports = {
+  hasRoleAssistantTestSubject,
+  runPublishedCaseAsSubject,
+  evaluationFromJobCase,
+  selectedSubject
+};