@aifabrix/builder 2.52.0 → 2.52.1

package/lib/commands/repair-datasource-sync-operations.js

@@ -108,7 +108,10 @@ function ensureSyncOperationScaffold(parsed) {
     parsed.execution = { engine: 'cip' };
   }
   if (!parsed.execution.cip || typeof parsed.execution.cip !== 'object') {
-    parsed.execution.cip = { operations: {} };
+    parsed.execution.cip = { version: '1.0', operations: {} };
+  }
+  if (!parsed.execution.cip.version) {
+    parsed.execution.cip.version = '1.0';
   }
   if (!parsed.execution.cip.operations || typeof parsed.execution.cip.operations !== 'object') {
     parsed.execution.cip.operations = {};

package/lib/commands/role-assistant-test-output.js

@@ -0,0 +1,200 @@
+/**
+ * Role Assistant test CLI envelope + human summary output.
+ * @fileoverview Split from role-assistant.js for max-lines / complexity
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { VERDICT } = require('../lifecycle/product-model');
+const {
+  sectionTitle,
+  headerKeyValue,
+  formatSuccessLine,
+  formatSuccessParagraph,
+  formatWarningLine,
+  formatBlockingError,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+
+/**
+ * Bucket a lifecycle step status into ok | failed | skipped | other.
+ * @param {string} status
+ * @returns {'ok'|'failed'|'skipped'|'other'}
+ */
+function bucketStepStatus(status) {
+  const normalized = String(status || 'ok').toLowerCase();
+  if (normalized === 'ok' || normalized === 'verified' || normalized === 'passed') {
+    return 'ok';
+  }
+  if (normalized === 'failed' || normalized === 'error') {
+    return 'failed';
+  }
+  if (normalized === 'skipped' || normalized === 'n/a' || normalized === 'not_applicable') {
+    return 'skipped';
+  }
+  return 'other';
+}
+
+/**
+ * Summarize lifecycle stepsRun rows (API uses step/status/datasourceKey, not pillar).
+ * @param {Array<Object|string>} steps
+ * @returns {string}
+ */
+function formatStepsRunSummary(steps) {
+  const byStep = Object.create(null);
+  for (const row of steps) {
+    if (!row || typeof row !== 'object') {
+      const label = String(row);
+      byStep[label] = byStep[label] || { ok: 0, failed: 0, skipped: 0, other: 0 };
+      byStep[label].other += 1;
+      continue;
+    }
+    const stepName = String(row.step || row.pillar || row.name || 'step').trim() || 'step';
+    const status = row.status || (row.success === false ? 'failed' : 'ok');
+    byStep[stepName] = byStep[stepName] || { ok: 0, failed: 0, skipped: 0, other: 0 };
+    byStep[stepName][bucketStepStatus(status)] += 1;
+  }
+  return Object.keys(byStep)
+    .map((stepName) => {
+      const counts = byStep[stepName];
+      const parts = [];
+      if (counts.ok) parts.push(`${counts.ok} ok`);
+      if (counts.failed) parts.push(`${counts.failed} failed`);
+      if (counts.skipped) parts.push(`${counts.skipped} skipped`);
+      if (counts.other) parts.push(`${counts.other} other`);
+      return parts.length > 0 ? `${stepName} (${parts.join(', ')})` : stepName;
+    })
+    .join('; ');
+}
+
+function mapCaseEnvelopeRow(row) {
+  return {
+    caseId: row.caseId,
+    sourceFile: row.sourceFile,
+    passed: row.passed,
+    lifecycleState: row.lifecycleState,
+    assertions: row.assertions,
+    failedAssertions: row.failedAssertions,
+    warnings: Array.isArray(row.warnings) ? row.warnings : [],
+    execution: row.execution || null
+  };
+}
+
+function attachEnvelopeCases(envelope, caseResult) {
+  if (Array.isArray(caseResult)) {
+    envelope.cases = caseResult.map(mapCaseEnvelopeRow);
+    const passed = envelope.cases.filter((c) => c.passed).length;
+    envelope.summary = {
+      total: envelope.cases.length,
+      passed,
+      failed: envelope.cases.length - passed
+    };
+    envelope.case = envelope.cases.length === 1 ? envelope.cases[0] : null;
+    return;
+  }
+  if (caseResult) {
+    envelope.case = mapCaseEnvelopeRow(caseResult);
+  }
+}
+
+function buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult = null) {
+  const report = result.report || {};
+  const multiCase = Array.isArray(caseResult) && caseResult.length > 1;
+  const envelope = {
+    roleKey,
+    command: 'role-assistant test',
+    mode: opts.suite || multiCase ? 'suite' : 'single',
+    suite: opts.suite || null,
+    verdict,
+    portalUrl,
+    openApiPublished: result.openApiPublished === true,
+    certification: report.certification || null,
+    recommendations: Array.isArray(report.recommendations) ? report.recommendations : [],
+    warnings: Array.isArray(report.warnings) ? report.warnings : [],
+    stepsRun: result.stepsRun || [],
+    case: null,
+    cases: null,
+    summary: null
+  };
+  attachEnvelopeCases(envelope, caseResult);
+  if (opts.verbose || opts.debug) {
+    envelope.report = report;
+  }
+  if (opts.debug) {
+    envelope.debug = {
+      observation: caseResult && !Array.isArray(caseResult) ? caseResult.observation : null,
+      lifecycleResult: result
+    };
+  }
+  return envelope;
+}
+
+function displayCaseResultSummary(caseResult) {
+  if (!caseResult) {
+    return;
+  }
+  logger.log(headerKeyValue('Case:', caseResult.caseId));
+  logger.log(headerKeyValue('Case file:', caseResult.sourceFile));
+  logger.log(headerKeyValue('Observed state:', caseResult.lifecycleState));
+  if (caseResult.execution) {
+    logger.log(headerKeyValue('Execution id:', caseResult.execution.processExecutionId || 'n/a'));
+    logger.log(headerKeyValue('Final runtime status:', caseResult.execution.finalStatus || 'n/a'));
+  }
+  if (caseResult.passed) {
+    logger.log(formatSuccessLine('Case assertions passed.'));
+    const warnings = Array.isArray(caseResult.warnings) ? caseResult.warnings : [];
+    for (const row of warnings) {
+      logger.log(formatWarningLine(row.message || String(row)));
+    }
+    return;
+  }
+  logger.log(formatBlockingError('Case assertions failed.'));
+  for (const row of caseResult.failedAssertions) {
+    logger.log(formatWarningLine(row.message));
+  }
+}
+
+function displayPortalAndVerdict(portalUrl, verdict) {
+  if (portalUrl) {
+    logger.log(headerKeyValue('Portal:', portalUrl));
+  } else {
+    logger.log(formatWarningLine('Portal link unavailable. Configure dataplane public URL and retry.'));
+  }
+  const verdictMessage =
+    verdict === VERDICT.VERIFIED
+      ? 'Lifecycle checks passed. Open portal for full execution steps and logs.'
+      : 'Lifecycle checks are not fully verified. Open portal to inspect blocking steps.';
+  if (verdict === VERDICT.VERIFIED) {
+    logger.log(formatSuccessParagraph(verdictMessage));
+  } else {
+    logger.log(formatWarningLine(verdictMessage));
+  }
+}
+
+function displayRoleAssistantTestSummary(roleKey, verdict, portalUrl, result, caseResult = null) {
+  logger.log('');
+  logger.log(sectionTitle(`${String(roleKey).toUpperCase()} ROLE ASSISTANT TEST`));
+  logger.log('');
+  logger.log(headerKeyValue('Role key:', roleKey));
+  displayPortalAndVerdict(portalUrl, verdict);
+  const steps = Array.isArray(result.stepsRun) ? result.stepsRun : [];
+  if (steps.length > 0) {
+    logger.log(metadata(`Steps run: ${formatStepsRunSummary(steps)}`));
+  }
+  if (Array.isArray(caseResult)) {
+    for (const row of caseResult) {
+      displayCaseResultSummary(row);
+    }
+    const passed = caseResult.filter((c) => c.passed).length;
+    logger.log(headerKeyValue('Suite summary:', `${passed}/${caseResult.length} passed`));
+    return;
+  }
+  displayCaseResultSummary(caseResult);
+}
+
+module.exports = {
+  formatStepsRunSummary,
+  buildRoleAssistantTestEnvelope,
+  displayRoleAssistantTestSummary
+};

package/lib/commands/role-assistant.js

@@ -8,6 +8,7 @@
 
 'use strict';
 
+const path = require('path');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const {
@@ -22,6 +23,11 @@ const {
   loadRoleAssistantTestCase,
   evaluateRoleAssistantTestCase
 } = require('../role-assistant/test-cases');
+const {
+  resolveCasesRoot,
+  discoverSuiteCaseFiles,
+  filterDiscoveredCases
+} = require('../role-assistant/test-suite');
 const {
   isExecutableRoleAssistantCase,
   runRoleAssistantCaseLifecycle,
@@ -32,68 +38,18 @@ const { collectString } = require('./governance');
 const {
   sectionTitle,
   headerKeyValue,
-  formatSuccessLine,
-  formatSuccessParagraph,
-  formatWarningLine,
-  formatBlockingError,
   metadata
 } = require('../utils/cli-test-layout-chalk');
+const {
+  formatStepsRunSummary,
+  buildRoleAssistantTestEnvelope,
+  displayRoleAssistantTestSummary
+} = require('./role-assistant-test-output');
 const {
   bareRoleKey,
   roleAssistantSystemKey
 } = require('../utils/role-assistant-paths');
 
-/**
- * Bucket a lifecycle step status into ok | failed | skipped | other.
- * @param {string} status
- * @returns {'ok'|'failed'|'skipped'|'other'}
- */
-function bucketStepStatus(status) {
-  const normalized = String(status || 'ok').toLowerCase();
-  if (normalized === 'ok' || normalized === 'verified' || normalized === 'passed') {
-    return 'ok';
-  }
-  if (normalized === 'failed' || normalized === 'error') {
-    return 'failed';
-  }
-  if (normalized === 'skipped' || normalized === 'n/a' || normalized === 'not_applicable') {
-    return 'skipped';
-  }
-  return 'other';
-}
-
-/**
- * Summarize lifecycle stepsRun rows (API uses step/status/datasourceKey, not pillar).
- * @param {Array<Object|string>} steps
- * @returns {string}
- */
-function formatStepsRunSummary(steps) {
-  const byStep = Object.create(null);
-  for (const row of steps) {
-    if (!row || typeof row !== 'object') {
-      const label = String(row);
-      byStep[label] = byStep[label] || { ok: 0, failed: 0, skipped: 0, other: 0 };
-      byStep[label].other += 1;
-      continue;
-    }
-    const stepName = String(row.step || row.pillar || row.name || 'step').trim() || 'step';
-    const status = row.status || (row.success === false ? 'failed' : 'ok');
-    byStep[stepName] = byStep[stepName] || { ok: 0, failed: 0, skipped: 0, other: 0 };
-    byStep[stepName][bucketStepStatus(status)] += 1;
-  }
-  return Object.keys(byStep)
-    .map((stepName) => {
-      const counts = byStep[stepName];
-      const parts = [];
-      if (counts.ok) parts.push(`${counts.ok} ok`);
-      if (counts.failed) parts.push(`${counts.failed} failed`);
-      if (counts.skipped) parts.push(`${counts.skipped} skipped`);
-      if (counts.other) parts.push(`${counts.other} other`);
-      return parts.length > 0 ? `${stepName} (${parts.join(', ')})` : stepName;
-    })
-    .join('; ');
-}
-
 function roleAssistantHelpAfter() {
   return `
 Examples:
@@ -101,8 +57,9 @@ Examples:
   $ aifabrix role-assistant test customer-support-bot --case smoke
   $ aifabrix role-assistant test customer-support-bot --case tests/customer-address-change.yaml
   $ aifabrix role-assistant test customer-support-bot --subject-email ops@example.com
-  $ aifabrix role-assistant test customer-support-bot --json
-  $ aifabrix role-assistant test customer-support-bot --publish --force
+  $ aifabrix role-assistant test customer-support-bot --suite 001
+  $ aifabrix role-assistant test customer-support-bot --list-cases
+  $ aifabrix role-assistant test customer-support-bot --suite 001 --fail-fast --json
 
 Notes:
   - Uses the public/running Role Assistant on the dataplane by default (does not publish local datasources).
@@ -110,6 +67,7 @@ Notes:
   - Runs lifecycle checks, then prints a portal deep link for full step-by-step status.
   - Case files with input.message/input.content execute Work Hub plan→accept (or work.start when executionPath: intent).
   - answers[] and approvals[] are matched to runtime wait payloads (questionKey/requestKey/waitReason).
+  - --suite runs all YAML under tests/role-assistant/ra-<roleKey>/<suite>/ (or --cases-root).
   - Use the portal URL for detailed human review while automation reads CLI/JSON output.
 `;
 }
@@ -146,96 +104,123 @@ function normalizeRoleAssistantTestOptions(options, cmd) {
     certificationProfile: options.certificationProfile || 'bronze',
     case: trimOptionalString(options.case),
     testsDir: trimOptionalString(options.testsDir),
+    suite: trimOptionalString(options.suite),
+    casesRoot: trimOptionalString(options.casesRoot),
+    listCases: optionOrFlag(options, 'listCases', cmd, '--list-cases'),
+    failFast: optionOrFlag(options, 'failFast', cmd, '--fail-fast'),
     run: true
   };
 }
 
-function buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult = null) {
-  const report = result.report || {};
-  const envelope = {
-    roleKey,
-    command: 'role-assistant test',
-    verdict,
-    portalUrl,
-    openApiPublished: result.openApiPublished === true,
-    certification: report.certification || null,
-    recommendations: Array.isArray(report.recommendations) ? report.recommendations : [],
-    warnings: Array.isArray(report.warnings) ? report.warnings : [],
-    stepsRun: result.stepsRun || [],
-    case: caseResult
-      ? {
-        caseId: caseResult.caseId,
-        sourceFile: caseResult.sourceFile,
-        passed: caseResult.passed,
-        lifecycleState: caseResult.lifecycleState,
-        assertions: caseResult.assertions,
-        failedAssertions: caseResult.failedAssertions,
-        warnings: Array.isArray(caseResult.warnings) ? caseResult.warnings : [],
-        execution: caseResult.execution || null
-      }
-      : null
-  };
-  if (opts.verbose || opts.debug) {
-    envelope.report = report;
+function computeRoleAssistantExitCode(verdict, caseResult) {
+  if (Array.isArray(caseResult)) {
+    if (caseResult.some((row) => row && row.passed === false)) {
+      return 2;
+    }
+    return 0;
   }
-  if (opts.debug) {
-    envelope.debug = {
-      observation: caseResult ? caseResult.observation : null,
-      lifecycleResult: result
-    };
+  if (caseResult) {
+    return caseResult.passed ? 0 : 2;
+  }
+  if (verdict === VERDICT.VERIFIED) {
+    return 0;
   }
-  return envelope;
+  return exitCodeFromVerdict(verdict, { partial: verdict === VERDICT.NOT_VERIFIED });
 }
 
-function displayCaseResultSummary(caseResult) {
-  if (!caseResult) {
-    return;
+function listRoleAssistantCases(roleKey, opts) {
+  const root = resolveCasesRoot(roleKey, { casesRoot: opts.casesRoot || undefined });
+  const rows = discoverSuiteCaseFiles(root, { suite: opts.suite || undefined });
+  const filtered = filterDiscoveredCases(rows, opts.case);
+  if (opts.json) {
+    logger.log(
+      JSON.stringify(
+        {
+          roleKey: bareRoleKey(roleKey),
+          command: 'role-assistant test',
+          mode: 'list-cases',
+          casesRoot: root,
+          cases: filtered.map((r) => ({
+            suite: r.suite,
+            file: r.file,
+            path: r.absPath,
+            caseIdHint: r.caseIdHint
+          }))
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    logger.log(sectionTitle('ROLE ASSISTANT CASES'));
+    logger.log(headerKeyValue('Cases root:', root));
+    for (const row of filtered) {
+      logger.log(`${row.suite}\t${row.file}\t${row.absPath}`);
+    }
+    logger.log(metadata(`total ${filtered.length}`));
   }
-  logger.log(headerKeyValue('Case:', caseResult.caseId));
-  logger.log(headerKeyValue('Case file:', caseResult.sourceFile));
-  logger.log(headerKeyValue('Observed state:', caseResult.lifecycleState));
-  if (caseResult.execution) {
-    logger.log(headerKeyValue('Execution id:', caseResult.execution.processExecutionId || 'n/a'));
-    logger.log(headerKeyValue('Final runtime status:', caseResult.execution.finalStatus || 'n/a'));
+  return 0;
+}
+
+async function resolveSuiteCaseResults(systemKey, opts, result, verdict, portalUrl) {
+  const root = resolveCasesRoot(systemKey, { casesRoot: opts.casesRoot || undefined });
+  const discovered = discoverSuiteCaseFiles(root, { suite: opts.suite || undefined });
+  const selected = filterDiscoveredCases(discovered, opts.case);
+  if (selected.length === 0) {
+    throw new Error(
+      `No role-assistant cases found under ${root}` +
+        (opts.suite ? ` suite=${opts.suite}` : '')
+    );
   }
-  if (caseResult.passed) {
-    logger.log(formatSuccessLine('Case assertions passed.'));
-    const warnings = Array.isArray(caseResult.warnings) ? caseResult.warnings : [];
-    for (const row of warnings) {
-      logger.log(formatWarningLine(row.message || String(row)));
+  const outcomes = [];
+  for (const row of selected) {
+    const caseOpts = { ...opts, case: row.absPath, testsDir: path.dirname(row.absPath) };
+    const one = await resolveRoleAssistantCaseResult(systemKey, caseOpts, result, verdict, portalUrl);
+    outcomes.push(one);
+    if (opts.failFast && one && one.passed === false) {
+      break;
     }
-    return;
-  }
-  logger.log(formatBlockingError('Case assertions failed.'));
-  for (const row of caseResult.failedAssertions) {
-    logger.log(formatWarningLine(row.message));
   }
+  return outcomes;
 }
 
-function displayRoleAssistantTestSummary(roleKey, verdict, portalUrl, result, caseResult = null) {
-  logger.log('');
-  logger.log(sectionTitle(`${String(roleKey).toUpperCase()} ROLE ASSISTANT TEST`));
-  logger.log('');
-  logger.log(headerKeyValue('Role key:', roleKey));
-  if (portalUrl) {
-    logger.log(headerKeyValue('Portal:', portalUrl));
+async function runRoleAssistantTestAction(roleKey, options, cmd) {
+  const opts = normalizeRoleAssistantTestOptions(options, cmd);
+  const systemKey = roleAssistantSystemKey(roleKey);
+  const displayKey = bareRoleKey(roleKey);
+
+  if (opts.listCases) {
+    return listRoleAssistantCases(systemKey, opts);
+  }
+
+  const result = await runLifecycleForExternalSystem(systemKey, opts);
+  const verdict = lifecycleVerdictFromReport(result.report || {});
+  const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, systemKey);
+
+  let caseResult = null;
+  if (opts.suite) {
+    caseResult = await resolveSuiteCaseResults(systemKey, opts, result, verdict, portalUrl);
   } else {
-    logger.log(formatWarningLine('Portal link unavailable. Configure dataplane public URL and retry.'));
+    caseResult = await resolveRoleAssistantCaseResult(systemKey, opts, result, verdict, portalUrl);
   }
-  const verdictMessage =
-    verdict === VERDICT.VERIFIED
-      ? 'Lifecycle checks passed. Open portal for full execution steps and logs.'
-      : 'Lifecycle checks are not fully verified. Open portal to inspect blocking steps.';
-  if (verdict === VERDICT.VERIFIED) {
-    logger.log(formatSuccessParagraph(verdictMessage));
+
+  if (opts.json) {
+    logger.log(
+      JSON.stringify(
+        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult),
+        null,
+        2
+      )
+    );
   } else {
-    logger.log(formatWarningLine(verdictMessage));
+    displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
   }
-  const steps = Array.isArray(result.stepsRun) ? result.stepsRun : [];
-  if (steps.length > 0) {
-    logger.log(metadata(`Steps run: ${formatStepsRunSummary(steps)}`));
+
+  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
   }
-  displayCaseResultSummary(caseResult);
+  return exitCode;
 }
 
 async function resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, portalUrl) {
@@ -272,44 +257,6 @@ async function resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, po
   return evaluation;
 }
 
-function computeRoleAssistantExitCode(verdict, caseResult) {
-  if (caseResult) {
-    return caseResult.passed ? 0 : 2;
-  }
-  if (verdict === VERDICT.VERIFIED) {
-    return 0;
-  }
-  return exitCodeFromVerdict(verdict, { partial: verdict === VERDICT.NOT_VERIFIED });
-}
-
-async function runRoleAssistantTestAction(roleKey, options, cmd) {
-  const opts = normalizeRoleAssistantTestOptions(options, cmd);
-  // Dataplane ExternalSystem key is always ra-{roleKey}; bare roleKey is display/settings only.
-  const systemKey = roleAssistantSystemKey(roleKey);
-  const displayKey = bareRoleKey(roleKey);
-  const result = await runLifecycleForExternalSystem(systemKey, opts);
-  const verdict = lifecycleVerdictFromReport(result.report || {});
-  const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, systemKey);
-  const caseResult = await resolveRoleAssistantCaseResult(systemKey, opts, result, verdict, portalUrl);
-
-  if (opts.json) {
-    logger.log(
-      JSON.stringify(
-        buildRoleAssistantTestEnvelope(displayKey, verdict, portalUrl, result, opts, caseResult),
-        null,
-        2
-      )
-    );
-  } else {
-    displayRoleAssistantTestSummary(displayKey, verdict, portalUrl, result, caseResult);
-  }
-
-  const exitCode = computeRoleAssistantExitCode(verdict, caseResult);
-  if (exitCode !== 0) {
-    process.exit(exitCode);
-  }
-}
-
 async function roleAssistantTestHandler(roleKey, options, cmd) {
   try {
     await runRoleAssistantTestAction(roleKey, options, cmd);
@@ -330,6 +277,16 @@ function setupRoleAssistantCommands(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('--case <caseIdOrPath>', 'Run and evaluate one role-assistant test case')
     .option('--tests-dir <dir>', 'Override role-assistant test case directory')
+    .option(
+      '--suite <suiteId>',
+      'Run all YAML cases under tests/role-assistant/ra-<roleKey>/<suiteId>/'
+    )
+    .option(
+      '--cases-root <dir>',
+      'Override cases root (default: tests/role-assistant/ra-<roleKey>/)'
+    )
+    .option('--list-cases', 'List discoverable case files and exit')
+    .option('--fail-fast', 'Stop suite run after the first failing case')
     .option('-v, --verbose', 'Include full lifecycle report payload in --json output')
     .option('-d, --debug', 'Write debug logs under role-assistant/<roleKey>/logs/')
     .option(
@@ -367,5 +324,7 @@ module.exports = {
   buildRoleAssistantTestEnvelope,
   computeRoleAssistantExitCode,
   resolveRoleAssistantCaseResult,
+  resolveSuiteCaseResults,
+  listRoleAssistantCases,
   formatStepsRunSummary
 };

package/lib/datasource/capability/capability-resolve.js

@@ -6,7 +6,7 @@
  * @version 2.0.0
  */
 
-const { capabilitiesIncludes } = require('./capability-manifest');
+const { capabilitiesIncludes, capabilityKeyFromEntry } = require('./capability-manifest');
 
 /**
  * @param {object|undefined} operations
@@ -44,6 +44,16 @@ function resolveSingleOpsKey(operations, logicalKey, label) {
   );
 }
 
+/**
+ * @param {unknown} entry
+ * @param {string} userKey
+ * @returns {boolean}
+ */
+function capabilityEntryMatches(entry, userKey) {
+  const key = capabilityKeyFromEntry(entry);
+  return Boolean(key) && key.toLowerCase() === String(userKey).toLowerCase();
+}
+
 /**
  * For --from on copy: when capabilities[] is non-empty, the name must appear there (case-insensitive).
  *
@@ -56,14 +66,14 @@ function resolveSourceCapabilityForCopy(doc, userKey) {
   const u = String(userKey).trim();
   const caps = doc.capabilities;
   if (Array.isArray(caps) && caps.length > 0) {
-    const hit = caps.find((c) => String(c).toLowerCase() === u.toLowerCase());
+    const hit = caps.find((c) => capabilityEntryMatches(c, u));
     if (hit === undefined) {
       throw new Error(
         `Source capability "${userKey}" not found in capabilities[]. ` +
           'Use a name that appears in capabilities[] (case-insensitive match is allowed).'
       );
     }
-    return String(hit);
+    return capabilityKeyFromEntry(hit) || u;
   }
   return u;
 }
@@ -79,9 +89,9 @@ function resolveLogicalNameForRemove(doc, userKey) {
   const u = String(userKey).trim();
   const caps = doc.capabilities;
   if (Array.isArray(caps) && caps.length > 0) {
-    const hit = caps.find((c) => String(c).toLowerCase() === u.toLowerCase());
+    const hit = caps.find((c) => capabilityEntryMatches(c, u));
     if (hit !== undefined) {
-      return String(hit);
+      return capabilityKeyFromEntry(hit) || u;
     }
   }
   return u;

package/lib/datasource/capability/copy-operations.js

@@ -7,7 +7,11 @@
  */
 
 const { rewriteCapabilityReferences } = require('./reference-rewrite');
-const { capabilityKeyFromEntry } = require('./capability-manifest');
+const {
+  capabilityKeyFromEntry,
+  capabilitiesIncludes,
+  buildCapabilityObject
+} = require('./capability-manifest');
 const { jsonPointerPath } = require('./json-pointer');
 const { buildBasicExposureProfileArray } = require('./basic-exposure');
 const {
@@ -256,14 +260,20 @@ function appendCapabilityList(doc, resolvedAs, patchOperations, updatedSections)
   if (!Array.isArray(doc.capabilities)) {
     doc.capabilities = [];
   }
-  if (doc.capabilities.includes(resolvedAs)) {
+  if (capabilitiesIncludes(doc.capabilities, resolvedAs)) {
     return;
   }
-  doc.capabilities.push(resolvedAs);
+  const usesObjects = doc.capabilities.some(
+    (entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+  );
+  const value = usesObjects
+    ? buildCapabilityObject(resolvedAs, doc.displayName || doc.key || 'records')
+    : resolvedAs;
+  doc.capabilities.push(value);
   patchOperations.push({
     op: 'add',
     path: '/capabilities/-',
-    value: resolvedAs
+    value
   });
   updatedSections.push(`capabilities[]: ${resolvedAs}`);
 }