@aifabrix/builder 2.44.2 → 2.44.4

package/.npmrc.token

@@ -1 +1 @@
-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
+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

package/integration/roundtrip-test-local/README.md

@@ -123,8 +123,7 @@ Options:
   -e, --env <env>                    Environment: dev, tst, or pro
   -v, --verbose                      Show detailed step output and poll progress
   --debug                            Include debug output and write log to integration/roundtrip-test-local/logs/
-  --test-crud                        Enable CRUD lifecycle test (body testCrud: true)
-  --record-id <id>                   Record ID for test (body recordId)
+  --no-run-scenarios                 Skip expanding testPayload.scenarios in capacity step
   --no-cleanup                       Disable cleanup after test (body cleanup: false)
   --primary-key-value <value|@path>  Primary key value or path to JSON file (e.g. @pk.json) for body primaryKeyValue
   --no-async                         Use sync mode (no polling); single POST, no asyncRun

package/integration/roundtrip-test-local2/README.md

@@ -123,8 +123,7 @@ Options:
   -e, --env <env>                    Environment: dev, tst, or pro
   -v, --verbose                      Show detailed step output and poll progress
   --debug                            Include debug output and write log to integration/roundtrip-test-local2/logs/
-  --test-crud                        Enable CRUD lifecycle test (body testCrud: true)
-  --record-id <id>                   Record ID for test (body recordId)
+  --no-run-scenarios                 Skip expanding testPayload.scenarios in capacity step
   --no-cleanup                       Disable cleanup after test (body cleanup: false)
   --primary-key-value <value|@path>  Primary key value or path to JSON file (e.g. @pk.json) for body primaryKeyValue
   --no-async                         Use sync mode (no polling); single POST, no asyncRun

package/jest.projects.js

@@ -72,6 +72,9 @@ const defaultProject = {
       '/tests/lib/datasource/log-viewer.test.js',
       '\\\\tests\\\\lib\\\\datasource\\\\log-viewer.test.js',
       'lib/datasource/log-viewer.test.js',
+      '/tests/lib/datasource/log-viewer-structural.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\log-viewer-structural.test.js',
+      'lib/datasource/log-viewer-structural.test.js',
       '/tests/lib/commands/parameters-validate.test.js',
       '\\\\tests\\\\lib\\\\commands\\\\parameters-validate.test.js',
       'lib/commands/parameters-validate.test.js',
@@ -190,6 +193,10 @@ const defaultProject = {
       '\\\\tests\\\\lib\\\\validation\\\\schema-241-alignment.test.js',
       'lib/validation/schema-241-alignment.test.js',
       'schema-241-alignment\\.test\\.js',
+      '/tests/lib/utils/schema-resolver-order.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\schema-resolver-order.test.js',
+      'lib/utils/schema-resolver-order.test.js',
+      'schema-resolver-order\\.test\\.js',
       '/tests/lib/app/app.test.js',
       '\\\\tests\\\\lib\\\\app\\\\app.test.js',
       'lib/app/app.test.js',
@@ -222,7 +229,10 @@ const isolatedProjects = [
   makeIsolatedProject('datasource-validation-watch', [
     '**/tests/lib/utils/datasource-validation-watch.test.js'
   ]),
-  makeIsolatedProject('log-viewer', ['**/tests/lib/datasource/log-viewer.test.js']),
+  makeIsolatedProject('log-viewer', [
+    '**/tests/lib/datasource/log-viewer.test.js',
+    '**/tests/lib/datasource/log-viewer-structural.test.js'
+  ]),
   makeIsolatedProject('datasource-test-run-schema-sync', [
     '**/tests/lib/utils/datasource-test-run-schema-sync.test.js'
   ]),
@@ -285,6 +295,7 @@ const isolatedProjects = [
   makeIsolatedProject('generator-validation', ['**/tests/lib/generator/generator-validation.test.js']),
   makeIsolatedProject('secrets-databaselog', ['**/tests/lib/core/secrets-databaselog.test.js']),
   makeIsolatedProject('schema-241-alignment', ['**/tests/lib/validation/schema-241-alignment.test.js']),
+  makeIsolatedProject('schema-resolver-order', ['**/tests/lib/utils/schema-resolver-order.test.js']),
   makeIsolatedProject('app-module', ['**/tests/lib/app/app.test.js']),
   makeIsolatedProject('admin-secrets', ['**/tests/lib/core/admin-secrets.test.js'])
 ];

package/lib/api/certificates.api.js

@@ -5,6 +5,24 @@
  */
 
 const { ApiClient } = require('./index');
+const { normalizeDataplaneAuth } = require('./validation-run.api');
+
+/**
+ * @param {Object} authConfig
+ * @returns {Object}
+ */
+function dataplaneAuthForBearerGet(authConfig) {
+  if (!authConfig || typeof authConfig !== 'object') {
+    return authConfig;
+  }
+  if (authConfig.token || authConfig.clientId) {
+    return authConfig;
+  }
+  if (authConfig.apiKey) {
+    return { ...authConfig, token: authConfig.apiKey, type: authConfig.type || 'bearer' };
+  }
+  return normalizeDataplaneAuth(authConfig);
+}
 
 /**
  * Get active trusted integration certificate for a datasource.
@@ -18,7 +36,7 @@ const { ApiClient } = require('./index');
  * @returns {Promise<Object>} API envelope `{ success, data?, status, ... }`
  */
 async function getActiveIntegrationCertificate(dataplaneUrl, authConfig, systemKey, datasourceKey) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   const path = `/api/v1/systems/${encodeURIComponent(systemKey)}/datasources/${encodeURIComponent(
     datasourceKey
   )}/certificates/active`;
@@ -36,7 +54,7 @@ async function getActiveIntegrationCertificate(dataplaneUrl, authConfig, systemK
  * @returns {Promise<Object>}
  */
 async function listIntegrationCertificates(dataplaneUrl, authConfig, params = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   return await client.get('/api/v1/certificates', { params });
 }
 
@@ -51,7 +69,7 @@ async function listIntegrationCertificates(dataplaneUrl, authConfig, params = {}
  * @returns {Promise<Object>}
  */
 async function verifyIntegrationCertificate(dataplaneUrl, authConfig, body) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   return await client.post('/api/v1/certificates/verify', { body: body || {} });
 }
 

package/lib/api/types/certificates.types.js

@@ -22,7 +22,7 @@
  * @property {string} [issuedBy]
  * @property {string} [licenseLevelIssuer]
  * @property {string} [dataplaneVersion]
- * @property {('RS256'|'HS256')} [algorithm] RS256 production; HS256 local dev HMAC signer only
+ * @property {'RS256'} [algorithm] Integration certificate signing algorithm (RS256 only)
  * @property {string|null} [publicKey]
  * @property {string|null} [publicKeyFingerprint]
  * @property {Object} [metadata]

package/lib/app/show-display.js

@@ -11,7 +11,6 @@
 
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { truncatePublicKeyPreview } = require('./certification-show-enrich');
 
 function logSourceAndHeader(summary) {
   const isOffline = summary.source === 'offline';
@@ -263,23 +262,51 @@ function displayExternalAppBlock(summary) {
 }
 
 /**
- * Local certification + optional verify rows (external integrations).
- * @param {Object} summary
+ * Colored certification outcome from `status` string.
+ * @param {string} raw - lowercased status
+ * @returns {string}
  */
-function logCertificationSection(summary) {
-  if (!summary.isExternal) return;
-  logger.log('');
-  logger.log('🪪  Certification (local system file)');
-  const c = summary.localCertification;
-  if (!c || typeof c !== 'object') {
-    logger.log('  (none or unreadable)');
-  } else {
-    logger.log(`  enabled:     ${c.enabled}`);
-    logger.log(`  algorithm:   ${c.algorithm ?? '—'}`);
-    logger.log(`  issuer:      ${c.issuer ?? '—'}`);
-    logger.log(`  version:     ${c.version ?? '—'}`);
-    logger.log(`  publicKey:   ${truncatePublicKeyPreview(c.publicKey, 64)}`);
+function formatCertificationOutcome(raw) {
+  if (raw === 'passed') return chalk.green('passed');
+  if (raw === 'not_passed') return chalk.red('not_passed');
+  if (raw === 'pending') return chalk.yellow('pending');
+  return raw || '—';
+}
+
+/**
+ * Certification status line: enabled ✔/✖ plus outcome (passed / not_passed / pending).
+ * @param {Object} c - certification block from system file
+ * @returns {string}
+ */
+function formatCertificationStatusLine(c) {
+  const enabledTrue = c.enabled === true;
+  const enabledSym = enabledTrue ? chalk.green('✔') : chalk.red('✖');
+  const raw = (c.status && String(c.status).toLowerCase()) || '';
+  const outcome = formatCertificationOutcome(raw);
+  return `  Status:     ${enabledSym}  ${outcome}`;
+}
+
+/**
+ * Local certification fields from system file (TTY block).
+ * @param {Object} c
+ */
+function logCertificationLocalFileDetails(c) {
+  logger.log(formatCertificationStatusLine(c));
+  const levelStr =
+    c.level === undefined || c.level === null ? '' : String(c.level).trim();
+  if (levelStr) {
+    logger.log(`  Level:      ${levelStr}`);
   }
+  logger.log(`  algorithm:  ${c.algorithm ?? '—'}`);
+  logger.log(`  issuer:     ${c.issuer ?? '—'}`);
+  logger.log(`  version:    ${c.version ?? '—'}`);
+}
+
+/**
+ * Dataplane certification verify rows (when `--verify-cert` populated summary).
+ * @param {Object} summary
+ */
+function logCertificationVerifySection(summary) {
   if (summary.certificationVerifyRows && summary.certificationVerifyRows.length > 0) {
     logger.log('');
     logger.log('🪪  Certification verify (dataplane)');
@@ -303,6 +330,23 @@ function logCertificationSection(summary) {
   }
 }
 
+/**
+ * Local certification + optional verify rows (external integrations).
+ * @param {Object} summary
+ */
+function logCertificationSection(summary) {
+  if (!summary.isExternal) return;
+  logger.log('');
+  logger.log('🪪  Certification (local system file)');
+  const c = summary.localCertification;
+  if (!c || typeof c !== 'object') {
+    logger.log('  (none or unreadable)');
+  } else {
+    logCertificationLocalFileDetails(c);
+  }
+  logCertificationVerifySection(summary);
+}
+
 /**
  * Format and print human-readable show output (offline or online).
  * @param {Object} summary - Unified summary (buildOfflineSummaryFromDeployJson or buildOnlineSummary)

package/lib/certification/merge-certification-from-artifact.js

@@ -38,14 +38,14 @@ function pickArtifactForCertificationMerge(artifacts) {
 }
 
 /**
- * @param {string} algorithmUpper
  * @param {import('../api/types/certificates.types').CertificateArtifactResponse} art
+ * @param {Object} ex
  * @returns {string}
  */
-function hs256DevPublicKeyPlaceholder(algorithmUpper, art) {
-  if (algorithmUpper !== 'HS256') return '';
-  const cid = certificateIdToString(art.certificateId);
-  return `HS256-DEV-NO-PEM:${cid || 'integration-certificate'}`;
+function resolvePublicKey(art, ex) {
+  const fromArt = trimOrEmpty(art.publicKey);
+  if (fromArt) return fromArt;
+  return trimOrEmpty(ex.publicKey);
 }
 
 /**
@@ -53,13 +53,34 @@ function hs256DevPublicKeyPlaceholder(algorithmUpper, art) {
  * @param {Object} ex
  * @returns {string}
  */
-function resolvePublicKey(art, ex) {
-  const fromArt = trimOrEmpty(art.publicKey);
+function resolvePublicKeyFingerprint(art, ex) {
+  const fromArt = trimOrEmpty(art.publicKeyFingerprint);
   if (fromArt) return fromArt;
-  const fromExisting = trimOrEmpty(ex.publicKey);
-  if (fromExisting) return fromExisting;
-  const algorithmUpper = trimOrEmpty(art.algorithm).toUpperCase();
-  return hs256DevPublicKeyPlaceholder(algorithmUpper, art);
+  return trimOrEmpty(ex.publicKeyFingerprint);
+}
+
+/**
+ * @param {string} raw
+ * @returns {string} Normalized digest or empty when invalid
+ */
+function normalizeContractHash(raw) {
+  const s = trimOrEmpty(raw);
+  return CONTRACT_HASH_PATTERN.test(s) ? s : '';
+}
+
+/**
+ * @param {import('../api/types/certificates.types').CertificateArtifactResponse} art
+ * @param {Object} ex
+ * @returns {string}
+ */
+function resolveContractHash(art, ex) {
+  return (
+    normalizeContractHash(art.contractHash) ||
+    normalizeContractHash(art.integrationHash) ||
+    normalizeContractHash(ex.contractHash) ||
+    normalizeContractHash(ex.integrationHash) ||
+    ''
+  );
 }
 
 /**
@@ -92,6 +113,8 @@ function resolveVersion(art, ex) {
 
 const CERTIFICATION_LEVELS = new Set(['BRONZE', 'SILVER', 'GOLD', 'PLATINUM']);
 const CERTIFICATION_STATUSES = new Set(['passed', 'not_passed', 'pending']);
+/** Matches external-system.schema.json `certification.contractHash` pattern. */
+const CONTRACT_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
 
 /**
  * @param {string} raw
@@ -138,9 +161,10 @@ function resolveStatus(_art, ex) {
 }
 
 /**
- * Build `certification` object matching **external-system.schema.json** (required: enabled, publicKey, algorithm, issuer, version; optional status, level).
+ * Build `certification` object matching **external-system.schema.json** (required: enabled, publicKey, algorithm, issuer, version; optional status, level, publicKeyFingerprint, contractHash).
  * Fills gaps from `existingCertification` when the artifact omits publishable fields (common when dataplane redacts `publicKey`).
- * For **HS256** dev certificates with no PEM, uses a non-secret placeholder `publicKey` so the system file stays schema-valid.
+ * Dataplane issues **RS256** certificates with PEM `publicKey` and optional `publicKeyFingerprint` (sha256:… of SPKI); merge output uses **RS256** only.
+ * Optional **contractHash** is copied from the certificate `contractHash` or legacy `integrationHash` when it matches `sha256:` + 64 hex.
  *
  * @param {import('../api/types/certificates.types').CertificateArtifactResponse|null} artifact
  * @param {Object|null|undefined} existingCertification - Current `system.certification`
@@ -160,13 +184,13 @@ function buildCertificationFromArtifact(artifact, existingCertification) {
   const versionStr = resolveVersion(art, ex);
   if (!versionStr) return null;
 
-  const algorithmUpper = trimOrEmpty(art.algorithm).toUpperCase();
-  const algorithm = algorithmUpper === 'HS256' ? 'HS256' : 'RS256';
+  const publicKeyFingerprint = resolvePublicKeyFingerprint(art, ex);
+  const contractHash = resolveContractHash(art, ex);
 
   const out = {
     enabled: true,
     publicKey,
-    algorithm,
+    algorithm: 'RS256',
     issuer,
     version: versionStr,
     status: resolveStatus(art, ex)
@@ -175,6 +199,12 @@ function buildCertificationFromArtifact(artifact, existingCertification) {
   if (level) {
     out.level = level;
   }
+  if (publicKeyFingerprint) {
+    out.publicKeyFingerprint = publicKeyFingerprint;
+  }
+  if (contractHash) {
+    out.contractHash = contractHash;
+  }
   return out;
 }
 

package/lib/certification/post-unified-cert-sync.js

@@ -10,6 +10,7 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { trySyncCertificationFromDataplaneForExternalApp } = require('./sync-after-external-command');
 const { cliOptsSkipCertSync } = require('./cli-cert-sync-skip');
+const { resolveDebugDisplayMode } = require('../utils/datasource-test-run-debug-display');
 
 /**
  * @async
@@ -17,14 +18,24 @@ const { cliOptsSkipCertSync } = require('./cli-cert-sync-skip');
  * @param {string} datasourceKey
  * @param {Object} options - CLI flags (app, noCertSync)
  * @param {string} label - Log label
+ * @param {Object|null} [envelope] - Last DatasourceTestRun (optional); used for certificateIssuance failed hint
  * @returns {Promise<void>}
  */
-async function afterUnifiedValidationCertSync(exitCode, datasourceKey, options, label) {
+async function afterUnifiedValidationCertSync(exitCode, datasourceKey, options, label, envelope = null) {
   if (exitCode !== 0 || cliOptsSkipCertSync(options)) return;
   try {
     const { resolveAppKeyForDatasource } = require('../datasource/resolve-app');
     const { appKey } = await resolveAppKeyForDatasource(datasourceKey, options.app);
-    await trySyncCertificationFromDataplaneForExternalApp(appKey, label);
+    let issuanceFailureHint = null;
+    if (envelope && envelope.certificateIssuance && envelope.certificateIssuance.status === 'failed') {
+      const ci = envelope.certificateIssuance;
+      issuanceFailureHint = [ci.reasonCode, ci.message].filter(Boolean).join(': ');
+    }
+    const verboseCertHints = resolveDebugDisplayMode(options.debug) !== null;
+    await trySyncCertificationFromDataplaneForExternalApp(appKey, label, {
+      issuanceFailureHint,
+      verboseCertHints
+    });
   } catch (e) {
     logger.log(chalk.yellow(`⚠ Certification sync (${label}) skipped: ${e.message}`));
   }

package/lib/certification/sync-after-external-command.js

@@ -16,9 +16,10 @@ const logger = require('../utils/logger');
  * @async
  * @param {string} appKey - Integration / system key
  * @param {string} label - Short label for logs (e.g. "validate", "datasource test")
+ * @param {Object} [extra] - Optional `{ issuanceFailureHint }` from last DatasourceTestRun.certificateIssuance (failed)
  * @returns {Promise<void>}
  */
-async function trySyncCertificationFromDataplaneForExternalApp(appKey, label) {
+async function trySyncCertificationFromDataplaneForExternalApp(appKey, label, extra = {}) {
   try {
     const { detectAppType } = require('../utils/paths');
     const t = await detectAppType(appKey).catch(() => null);
@@ -29,7 +30,7 @@ async function trySyncCertificationFromDataplaneForExternalApp(appKey, label) {
     const { maybeSyncSystemCertificationFromDataplane } = require('./sync-system-certification');
 
     validateSystemKeyFormat(appKey);
-    const { dataplaneUrl, authConfig } = await resolveDataplaneAndAuth(appKey);
+    const { dataplaneUrl, authConfig } = await resolveDataplaneAndAuth(appKey, { silent: true });
     if (!authConfig.token) {
       logger.log(chalk.gray(`Certification sync (${label}) skipped: no Bearer token (run aifabrix login).`));
       return;
@@ -42,7 +43,9 @@ async function trySyncCertificationFromDataplaneForExternalApp(appKey, label) {
       systemKey: manifest.key,
       dataplaneUrl,
       authConfig,
-      datasourceKeys: dsKeys
+      datasourceKeys: dsKeys,
+      issuanceFailureHint: extra && extra.issuanceFailureHint ? String(extra.issuanceFailureHint).trim() : null,
+      verboseCertHints: extra && extra.verboseCertHints === true
     });
   } catch (e) {
     logger.log(chalk.yellow(`⚠ Certification sync (${label}) skipped: ${e.message}`));

package/lib/certification/sync-system-certification.js

@@ -84,15 +84,43 @@ function tryWriteSystemCertification(systemFilePath, systemObj, nextCert) {
 /**
  * @param {Object|null} chosen
  * @param {'no_active'|'no_public_key'} detail
+ * @param {string|null} [issuanceFailureHint] - From last DatasourceTestRun.certificateIssuance when status failed
+ * @param {boolean} [verboseCertHints] - Extra gray lines and auto-issue detail (CLI `--debug`)
  */
-function logSkippedCertification(chosen, detail) {
+function logSkippedCertification(chosen, detail, issuanceFailureHint, verboseCertHints = false) {
   if (detail === 'no_active' || !chosen) {
-    logger.log(
-      chalk.yellow(
-        '⚠ Certification not written: dataplane has no active trusted certificate for this system/datasource scope yet. ' +
-          'Run a successful validation or E2E that issues a certificate, then upload or run cert sync again.'
-      )
-    );
+    const hint = issuanceFailureHint && String(issuanceFailureHint).trim();
+    const certNotPassed =
+      hint &&
+      (hint.includes('CERTIFICATION_NOT_PASSED') ||
+        hint.toLowerCase().includes('certification did not pass'));
+    if (certNotPassed) {
+      logger.log(
+        chalk.yellow(
+          '⚠ Certification not written: no active integration certificate because certification did not pass on the dataplane issuance validation pass.'
+        )
+      );
+      if (verboseCertHints) {
+        logger.log(
+          chalk.gray(
+            '  E2E can be green for every datasource while auto-issue still fails: issuance re-validates the whole system before signing.'
+          )
+        );
+        if (hint) {
+          logger.log(chalk.gray(`  Auto-issue detail: ${hint}`));
+        }
+      }
+    } else {
+      logger.log(
+        chalk.yellow(
+          '⚠ Certification not written: dataplane has no active trusted certificate for this system/datasource scope yet. ' +
+            'Fix auto-issue or signing (see hint), or run unified validation then upload or run cert sync again.'
+        )
+      );
+      if (hint && verboseCertHints) {
+        logger.log(chalk.gray(`  Auto-issue detail: ${hint}`));
+      }
+    }
     return;
   }
   logger.log(
@@ -111,13 +139,19 @@ function logSkippedCertification(chosen, detail) {
  * @param {string} params.dataplaneUrl
  * @param {Object} params.authConfig
  * @param {string[]} params.datasourceKeys
+ * @param {boolean} [params.verboseCertHints]
  * @returns {Promise<{ written: boolean, reason?: string }>}
  */
 async function syncSystemCertificationFromDataplane(params) {
-  const { systemKey, dataplaneUrl, authConfig, datasourceKeys } = params;
+  const { systemKey, dataplaneUrl, authConfig, datasourceKeys, issuanceFailureHint, verboseCertHints } = params;
   const resolved = resolvePrimarySystemFilePath(systemKey);
   if (!resolved) return { written: false, reason: 'no_system_file' };
-  if (!dataplaneUrl || !authConfig || !authConfig.token) {
+  const hasBearerLike =
+    authConfig &&
+    typeof authConfig === 'object' &&
+    ((typeof authConfig.token === 'string' && authConfig.token.trim()) ||
+      (typeof authConfig.apiKey === 'string' && authConfig.apiKey.trim()));
+  if (!dataplaneUrl || !authConfig || !hasBearerLike) {
     return { written: false, reason: 'no_auth' };
   }
 
@@ -137,7 +171,7 @@ async function syncSystemCertificationFromDataplane(params) {
   const nextCert = buildCertificationFromArtifact(chosen, existing);
   if (!nextCert) {
     const detail = chosen ? 'no_public_key' : 'no_active';
-    logSkippedCertification(chosen, detail);
+    logSkippedCertification(chosen, detail, issuanceFailureHint, verboseCertHints === true);
     return { written: false, reason: 'incomplete_certification', detail };
   }
 
@@ -154,7 +188,8 @@ async function syncSystemCertificationFromDataplane(params) {
  * @param {boolean} [params.noCertSync]
  * @returns {Promise<void>}
  */
-function logCertificationSyncNotWritten(r, label) {
+function logCertificationSyncNotWritten(r, label, verboseCertHints = false) {
+  if (r && r.reason === 'incomplete_certification' && !verboseCertHints) return;
   const prefix = label ? ` (${label})` : '';
   const map = {
     no_system_file: `No *-system* file found under integration folder for this key${prefix}.`,
@@ -168,21 +203,32 @@ function logCertificationSyncNotWritten(r, label) {
 }
 
 async function maybeSyncSystemCertificationFromDataplane(params) {
-  const { label, noCertSync, systemKey, dataplaneUrl, authConfig, datasourceKeys } = params;
+  const {
+    label,
+    noCertSync,
+    systemKey,
+    dataplaneUrl,
+    authConfig,
+    datasourceKeys,
+    issuanceFailureHint,
+    verboseCertHints
+  } = params;
   if (noCertSync === true) return;
   try {
     const r = await syncSystemCertificationFromDataplane({
       systemKey,
       dataplaneUrl,
       authConfig,
-      datasourceKeys
+      datasourceKeys,
+      issuanceFailureHint,
+      verboseCertHints
     });
     if (r.written) {
       logger.log(
         chalk.gray(`Updated certification block from dataplane${label ? ` (${label})` : ''} in system file.`)
       );
     } else if (r.reason) {
-      logCertificationSyncNotWritten(r, label);
+      logCertificationSyncNotWritten(r, label, verboseCertHints === true);
     }
   } catch (e) {
     logger.log(chalk.yellow(`⚠ Certification sync skipped: ${e.message}`));

package/lib/cli/setup-app.test-commands.js

@@ -54,6 +54,70 @@ function setupTestCommand(program) {
     });
 }
 
+/**
+ * First failed `certificateIssuance` across E2E datasource rows (for cert-sync hint).
+ * @param {Array<{ key?: string, datasourceTestRun?: { certificateIssuance?: { status?: string, reasonCode?: string, message?: string } } }>} results
+ * @returns {string|null}
+ */
+function firstIssuanceFailureHintFromE2eResults(results) {
+  const failed = [];
+  for (const row of results || []) {
+    const ci = row.datasourceTestRun && row.datasourceTestRun.certificateIssuance;
+    if (ci && ci.status === 'failed') {
+      failed.push({ key: row.key, ci });
+    }
+  }
+  if (failed.length === 0) return null;
+  const firstRc = failed[0].ci.reasonCode;
+  const sameAll = failed.every(f => f.ci.reasonCode === firstRc);
+  if (sameAll && failed.length > 1) {
+    const parts = [firstRc, failed[0].ci.message].filter(Boolean);
+    return `${parts.join(': ')} (${failed.length} datasource scopes; first: ${failed[0].key})`;
+  }
+  const parts = [failed[0].ci.reasonCode, failed[0].ci.message].filter(Boolean);
+  return `[${failed[0].key}] ${parts.join(': ')}`.trim();
+}
+
+/**
+ * External integration E2E: run, display, exit on aggregate, optional cert sync.
+ * @param {string} appName
+ * @param {Object} options
+ * @returns {Promise<void>}
+ */
+async function runExternalIntegrationE2EAndCertSync(appName, options) {
+  const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+  const { success, results } = await runTestE2EForExternalSystem(appName, {
+    env: options.env,
+    debug: options.debug,
+    verbose: options.verbose,
+    async: options.async !== false,
+    sync: options.sync === true
+  });
+  const { displayIntegrationTestResults } = require('../utils/external-system-display');
+  const datasourceResults = results.map(r => ({
+    key: r.key,
+    success: r.success,
+    error: r.error,
+    skipped: false,
+    datasourceTestRun: r.datasourceTestRun
+  }));
+  displayIntegrationTestResults(
+    { systemKey: appName, success, datasourceResults },
+    options.verbose,
+    { debug: options.debug, runType: 'e2e' }
+  );
+  const { computeSystemExitCodeFromDatasourceRows } = require('../utils/datasource-test-run-exit');
+  const exitCode = computeSystemExitCodeFromDatasourceRows(datasourceResults, {
+    warningsAsErrors: options.warningsAsErrors === true,
+    requireCert: options.requireCert === true
+  });
+  if (exitCode !== 0) process.exit(exitCode);
+  if (cliOptsSkipCertSync(options)) return;
+  const { trySyncCertificationFromDataplaneForExternalApp } = require('../certification/sync-after-external-command');
+  const issuanceFailureHint = firstIssuanceFailureHintFromE2eResults(results);
+  await trySyncCertificationFromDataplaneForExternalApp(appName, 'test-e2e', { issuanceFailureHint });
+}
+
 async function runTestE2ECommand(appName, options) {
   const pathsUtil = require('../utils/paths');
   const appType = await pathsUtil.detectAppType(appName).catch(() => null);
@@ -64,40 +128,7 @@ async function runTestE2ECommand(appName, options) {
     );
   }
   if (appType && appType.baseDir === 'integration') {
-    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
-    const { success, results } = await runTestE2EForExternalSystem(appName, {
-      env: options.env,
-      debug: options.debug,
-      verbose: options.verbose,
-      async: options.async !== false,
-      sync: options.sync === true
-    });
-    const { displayIntegrationTestResults } = require('../utils/external-system-display');
-    const datasourceResults = results.map(r => ({
-      key: r.key,
-      success: r.success,
-      error: r.error,
-      skipped: false,
-      datasourceTestRun: r.datasourceTestRun
-    }));
-    displayIntegrationTestResults(
-      {
-        systemKey: appName,
-        success,
-        datasourceResults
-      },
-      options.verbose,
-      { debug: options.debug, runType: 'e2e' }
-    );
-    const { computeSystemExitCodeFromDatasourceRows } = require('../utils/datasource-test-run-exit');
-    const exitCode = computeSystemExitCodeFromDatasourceRows(datasourceResults, {
-      warningsAsErrors: options.warningsAsErrors === true,
-      requireCert: options.requireCert === true
-    });
-    if (exitCode !== 0) process.exit(exitCode);
-    if (cliOptsSkipCertSync(options)) return;
-    const { trySyncCertificationFromDataplaneForExternalApp } = require('../certification/sync-after-external-command');
-    await trySyncCertificationFromDataplaneForExternalApp(appName, 'test-e2e');
+    await runExternalIntegrationE2EAndCertSync(appName, options);
     return;
   }
   const { runAppTestE2e } = require('../commands/app-test');
@@ -190,6 +221,7 @@ function setupInstallTestE2eLintCommands(program) {
 }
 
 module.exports = {
-  setupInstallTestE2eLintCommands
+  setupInstallTestE2eLintCommands,
+  firstIssuanceFailureHintFromE2eResults
 };