@aifabrix/builder 2.44.3 → 2.44.5

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

@@ -57,21 +57,28 @@ const defaultProject = {
       '/tests/lib/utils/cli-utils.test.js',
       '/tests/lib/utils/external-system-display.test.js',
       '/tests/lib/utils/dev-hosts-helper.test.js',
-      '/tests/lib/utils/declarative-url-matrix-d-reload.test.js',
+      '/tests/lib/utils/register-aifabrix-shell-env.test.js',
       '/tests/lib/utils/datasource-validation-watch.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\cli-utils.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\external-system-display.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\dev-hosts-helper.test.js',
-      '\\\\tests\\\\lib\\\\utils\\\\declarative-url-matrix-d-reload.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\register-aifabrix-shell-env.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\datasource-validation-watch.test.js',
       'lib/utils/dev-hosts-helper.test.js',
-      'lib/utils/declarative-url-matrix-d-reload.test.js',
+      'lib/utils/register-aifabrix-shell-env.test.js',
       'lib/utils/datasource-validation-watch.test.js',
       'dev-hosts-helper\\.test\\.js',
-      'declarative-url-matrix-d-reload\\.test\\.js',
+      'register-aifabrix-shell-env\\.test\\.js',
       '/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-run.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\log-viewer-structural.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\log-viewer-run.test.js',
+      'lib/datasource/log-viewer-structural.test.js',
+      'lib/datasource/log-viewer-run.test.js',
+      'log-viewer-run\\.test\\.js',
       '/tests/lib/commands/parameters-validate.test.js',
       '\\\\tests\\\\lib\\\\commands\\\\parameters-validate.test.js',
       'lib/commands/parameters-validate.test.js',
@@ -150,10 +157,6 @@ const defaultProject = {
       '\\\\tests\\\\lib\\\\utils\\\\paths-app-listing.test.js',
       'lib/utils/paths-app-listing.test.js',
       'paths-app-listing\\.test\\.js',
-      '/tests/lib/utils/url-declarative-truth-table-124.test.js',
-      '\\\\tests\\\\lib\\\\utils\\\\url-declarative-truth-table-124.test.js',
-      'lib/utils/url-declarative-truth-table-124.test.js',
-      'url-declarative-truth-table-124\\.test\\.js',
       '/tests/lib/generator/generator-external-rbac.test.js',
       '\\\\tests\\\\lib\\\\generator\\\\generator-external-rbac.test.js',
       'lib/generator/generator-external-rbac.test.js',
@@ -190,9 +193,17 @@ 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',
+      '/tests/lib/templates/application-frontdoor-paths.contract.test.js',
+      '\\\\tests\\\\lib\\\\templates\\\\application-frontdoor-paths.contract.test.js',
+      'lib/templates/application-frontdoor-paths.contract.test.js',
+      'application-frontdoor-paths\\.contract\\.test\\.js',
       '/tests/lib/core/admin-secrets.test.js',
       '\\\\tests\\\\lib\\\\core\\\\admin-secrets.test.js',
       'lib/core/admin-secrets.test.js'
@@ -214,21 +225,28 @@ const isolatedProjects = [
   makeIsolatedProject('cli-utils', ['**/tests/lib/utils/cli-utils.test.js']),
   makeIsolatedProject('external-system-display', ['**/tests/lib/utils/external-system-display.test.js']),
   makeIsolatedProject('dev-hosts-helper', ['**/tests/lib/utils/dev-hosts-helper.test.js']),
-  makeIsolatedProject('declarative-url-matrix-d-reload', [
-    '**/tests/lib/utils/declarative-url-matrix-d-reload.test.js'
-  ]),
   makeIsolatedProject('parameters-validate', ['**/tests/lib/commands/parameters-validate.test.js']),
   makeIsolatedProject('paths-app-listing', ['**/tests/lib/utils/paths-app-listing.test.js']),
   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',
+    '**/tests/lib/datasource/log-viewer-run.test.js'
+  ]),
+  makeIsolatedProject('register-aifabrix-shell-env', [
+    '**/tests/lib/utils/register-aifabrix-shell-env.test.js'
+  ]),
   makeIsolatedProject('datasource-test-run-schema-sync', [
     '**/tests/lib/utils/datasource-test-run-schema-sync.test.js'
   ]),
   makeIsolatedProject('infra-platform-contract', [
     '**/tests/lib/parameters/infra-platform-contract.test.js'
   ]),
+  makeIsolatedProject('application-frontdoor-paths-contract', [
+    '**/tests/lib/templates/application-frontdoor-paths.contract.test.js'
+  ]),
   makeIsolatedProject('database-secret-values', [
     '**/tests/lib/parameters/database-secret-values.test.js'
   ]),
@@ -273,9 +291,6 @@ const isolatedProjects = [
   makeIsolatedProject('helpers-ensure-admin-secrets', [
     '**/tests/lib/infrastructure/helpers-ensure-admin-secrets.test.js'
   ]),
-  makeIsolatedProject('url-declarative-truth-table-124', [
-    '**/tests/lib/utils/url-declarative-truth-table-124.test.js'
-  ]),
   makeIsolatedProject('secrets-generator', ['**/tests/lib/utils/secrets-generator.test.js']),
   makeIsolatedProject('app-uncovered-lines', ['**/tests/lib/app/app-uncovered-lines.test.js']),
   makeIsolatedProject('ensure-dev-certs-for-remote-docker', [
@@ -285,6 +300,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/wizard.types.js

@@ -260,12 +260,13 @@
  * @property {string} [source.serverUrl] - MCP server URL (for mcp-server)
  * @property {string} [source.token] - MCP token (for mcp-server, supports ${ENV_VAR})
  * @property {string} [source.platform] - Known platform (for known-platform)
+ * @property {string} [source.entityName] - Entity from discover-entities (openapi-file / openapi-url); skips interactive Step 4.5 when valid
  * @property {Object} [credential] - Credential configuration
  * @property {string} credential.action - Action ('create' | 'select' | 'skip')
  * @property {string} [credential.credentialIdOrKey] - Credential ID/key (for select)
  * @property {Object} [credential.config] - Credential config (for create)
  * @property {Object} [preferences] - Generation preferences
- * @property {string} [preferences.intent] - User intent (any descriptive text)
+ * @property {string} [preferences.intent] - User intent (any descriptive text, max 1000 chars)
  * @property {string} [preferences.fieldOnboardingLevel] - Field level ('full' | 'standard' | 'minimal')
  * @property {boolean} [preferences.enableOpenAPIGeneration] - Enable OpenAPI generation
  * @property {boolean} [preferences.enableMCP] - Enable MCP

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.help.js

@@ -56,7 +56,7 @@ Examples:
 Notes:
   - To run E2E for one datasource, use:
       aifabrix datasource test-e2e <datasourceKey>
-  - Optional --sync publishes local files to the dataplane first (external integration only).
+  - External integration: local system and datasource files are published to the dataplane before E2E (same as upload). Use --no-sync to exercise only config already deployed. The old --sync flag is a no-op (kept for scripts).
 `;
 
 module.exports = {

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

@@ -54,50 +54,81 @@ 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,
+    noSync: options.noSync === 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);
-  if (options.sync === true && appType && appType.baseDir === 'builder') {
+  if (options.noSync === true && appType && appType.baseDir === 'builder') {
     throw new Error(
-      'Option --sync applies only to external integration E2E (integration/<systemKey>/). ' +
-        'Remove --sync for builder app E2E, or use aifabrix upload from the integration folder first.'
+      'Option --no-sync applies only to external integration E2E (integration/<systemKey>/). ' +
+        'Remove --no-sync for builder app E2E.'
     );
   }
   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');
@@ -135,7 +166,11 @@ function setupTestE2eCommand(program) {
     .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
     .option(
       '--sync',
-      'Publish local system and datasource files to the dataplane before running E2E (same as aifabrix upload <systemKey>; external integration only)'
+      '(Deprecated; no-op.) Local integration files are published before E2E by default; use --no-sync to skip.'
+    )
+    .option(
+      '--no-sync',
+      'Skip publishing local integration files; E2E uses the system config already on the dataplane (external integration only)'
     )
     .option('--warnings-as-errors', 'Treat aggregate warn as failure (exit 1)')
     .option('--require-cert', 'Require certification passed on every datasource (exit 2 if not)')
@@ -190,6 +225,7 @@ function setupInstallTestE2eLintCommands(program) {
 }
 
 module.exports = {
-  setupInstallTestE2eLintCommands
+  setupInstallTestE2eLintCommands,
+  firstIssuanceFailureHintFromE2eResults
 };
 

package/lib/cli/setup-infra.js

@@ -18,7 +18,7 @@ const { resolveControllerUrl } = require('../utils/controller-url');
 const { handleLogin } = require('../commands/login');
 const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
-const { cleanBuilderAppDirs } = require('../commands/up-common');
+const { applyUpPlatformForceConfig, cleanBuilderAppDirs } = require('../commands/up-common');
 const {
   loadInfraStatusSummary,
   formatInfraStatusTitleLine,
@@ -184,10 +184,14 @@ function setupUpPlatformCommand(program) {
     .option('-r, --registry <url>', 'Override registry for all apps (e.g. myacr.azurecr.io)')
     .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
     .option('-i, --image <key>=<value>', 'Override image (e.g. keycloak=myreg/k:v1, miso-controller=myreg/m:v1, dataplane=myreg/d:v1); can be repeated', (v, prev) => (prev || []).concat([v]))
-    .option('-f, --force', 'Clean builder/keycloak, builder/miso-controller, builder/dataplane and re-fetch from templates')
+    .option(
+      '-f, --force',
+      'Reset CLI auth (clear all device/client tokens, set environment to dev, set default controller URL from developer-id), clean builder/keycloak, builder/miso-controller, builder/dataplane, then re-fetch from templates'
+    )
     .action(async(options) => {
       try {
         if (options.force) {
+          await applyUpPlatformForceConfig();
           await cleanBuilderAppDirs(['keycloak', 'miso-controller', 'dataplane']);
         }
         await handleUpMiso(options);

package/lib/cli/setup-utility.js

@@ -30,6 +30,24 @@ Examples:
   $ aifabrix validate --builder
 `;
 
+const REPAIR_HELP_AFTER = `
+Examples:
+  $ aifabrix repair hubspot-demo
+    Align manifest, system/datasource files, RBAC extract, env.template, and deploy JSON under integration/<systemKey>/.
+
+  $ aifabrix repair hubspot-demo --dry-run
+    Show what would change without writing files.
+
+  $ aifabrix repair hubspot-demo --auth oauth2
+    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, basic, …).
+
+  $ aifabrix repair hubspot-demo --rbac --expose --sync --test
+    Optional datasource fixes: RBAC roles/permissions, exposed.schema from attributes, default sync block, testPayload stubs.
+
+  $ aifabrix repair hubspot-demo --doc
+    Regenerate README.md from the current deployment manifest only (other drift fixes unchanged).
+`;
+
 /**
  * Resolve app path and type for split-json (integration first, then builder).
  *
@@ -118,7 +136,7 @@ function setupResolveCommand(program) {
         );
         logger.log(`✔ Generated .env file: ${envPath}`);
         if (envOnly) {
-          logger.log(chalk.gray('  (env-only mode: validation skipped; no application.yaml)'));
+          logger.log(chalk.gray('  (env-only mode: validation skipped; no application config file)'));
         } else if (!options.skipValidation) {
           const validate = require('../validation/validate');
           const result = await validate.validateAppOrFile(appName);
@@ -185,6 +203,7 @@ function setupRepairCommand(program) {
     .option('--expose', 'Set exposed.schema on each datasource from all fieldMappings.attributes keys (metadata.<key>); removes deprecated exposed.attributes if present')
     .option('--sync', 'Add default sync section to datasources that lack it')
     .option('--test', 'Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes')
+    .addHelpText('after', REPAIR_HELP_AFTER)
     .action(async(appName, options) => {
       try {
         const { repairExternalIntegration } = require('../commands/repair');