@aifabrix/builder 2.51.0 → 2.51.1

package/lib/commands/role-assistant.js

@@ -0,0 +1,313 @@
+/**
+ * Role Assistant CLI command group.
+ *
+ * @fileoverview role-assistant test command with portal deep-link output
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const {
+  runLifecycleForExternalSystem,
+  resolveLifecycleAuth
+} = require('./lifecycle-external');
+const { lifecycleVerdictFromReport } = require('./lifecycle-command-action');
+const { buildExternalSystemUiUrl } = require('../lifecycle/dataplane-ui-url');
+const { VERDICT } = require('../lifecycle/product-model');
+const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
+const {
+  loadRoleAssistantTestCase,
+  evaluateRoleAssistantTestCase
+} = require('../role-assistant/test-cases');
+const {
+  isExecutableRoleAssistantCase,
+  runRoleAssistantCaseLifecycle,
+  mergeCaseExecutionIntoLifecycleResult,
+  lifecycleVerdictFromCaseExecution
+} = require('../role-assistant/test-runner');
+const { collectString } = require('./governance');
+const {
+  sectionTitle,
+  headerKeyValue,
+  formatSuccessLine,
+  formatSuccessParagraph,
+  formatWarningLine,
+  formatBlockingError,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+
+function roleAssistantHelpAfter() {
+  return `
+Examples:
+  $ aifabrix role-assistant test customer-support-bot
+  $ 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
+
+Notes:
+  - Uses the public/running Role Assistant on the dataplane by default (does not publish local datasources).
+  - Use \`aifabrix upload <roleKey> --env …\` (or \`--publish\`) when you intentionally refresh the package.
+  - 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).
+  - Use the portal URL for detailed human review while automation reads CLI/JSON output.
+`;
+}
+
+function rawArgsInclude(cmd, flag) {
+  const raw = cmd && Array.isArray(cmd.rawArgs) ? cmd.rawArgs : [];
+  return raw.includes(flag);
+}
+
+function optionOrFlag(options, key, cmd, ...flags) {
+  if (options[key] === true) {
+    return true;
+  }
+  return flags.some((flag) => rawArgsInclude(cmd, flag));
+}
+
+function trimOptionalString(value) {
+  return value ? String(value).trim() : '';
+}
+
+function normalizeRoleAssistantTestOptions(options, cmd) {
+  // Role Assistant test uses the public/running digital worker by default.
+  // Opt in to publish with --publish (optional --force).
+  const wantsPublish = optionOrFlag(options, 'publish', cmd, '--publish');
+  return {
+    env: options.env || 'dev',
+    verbose: optionOrFlag(options, 'verbose', cmd, '-v', '--verbose'),
+    debug: optionOrFlag(options, 'debug', cmd, '-d', '--debug'),
+    json: optionOrFlag(options, 'json', cmd, '--json'),
+    noPublish: !wantsPublish,
+    force: optionOrFlag(options, 'force', cmd, '--force'),
+    subjectUserId: options.subjectUserId || [],
+    subjectEmail: options.subjectEmail || [],
+    certificationProfile: options.certificationProfile || 'bronze',
+    case: trimOptionalString(options.case),
+    testsDir: trimOptionalString(options.testsDir),
+    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;
+  }
+  if (opts.debug) {
+    envelope.debug = {
+      observation: 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 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));
+  } 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));
+  }
+  const steps = Array.isArray(result.stepsRun) ? result.stepsRun : [];
+  if (steps.length > 0) {
+    const labels = steps.map((row) => (row && row.pillar ? row.pillar : String(row)));
+    logger.log(metadata(`Steps run: ${labels.join(', ')}`));
+  }
+  displayCaseResultSummary(caseResult);
+}
+
+async function resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, portalUrl) {
+  if (!opts.case) {
+    return null;
+  }
+  const roleCase = loadRoleAssistantTestCase(roleKey, opts.case, {
+    testsDir: opts.testsDir || null
+  });
+  if (!isExecutableRoleAssistantCase(roleCase)) {
+    return evaluateRoleAssistantTestCase(roleCase, result, verdict, portalUrl);
+  }
+  const authContext = await resolveLifecycleAuth(roleKey, {
+    ...opts,
+    run: false,
+    noPublish: true
+  });
+  const executionResult = await runRoleAssistantCaseLifecycle(roleKey, roleCase, authContext, opts);
+  const executionVerdict = lifecycleVerdictFromCaseExecution(executionResult, verdict);
+  const evaluationInput = mergeCaseExecutionIntoLifecycleResult(result, executionResult);
+  const evaluation = evaluateRoleAssistantTestCase(
+    roleCase,
+    evaluationInput,
+    executionVerdict,
+    portalUrl
+  );
+  evaluation.execution = {
+    processExecutionId: executionResult.processExecutionId || null,
+    finalStatus: executionResult.finalStatus?.status || null,
+    waitReason: executionResult.finalStatus?.wait?.waitReason || null,
+    interactions: executionResult.interactions || [],
+    workResultError: executionResult.workResultError || null
+  };
+  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);
+  const result = await runLifecycleForExternalSystem(roleKey, opts);
+  const verdict = lifecycleVerdictFromReport(result.report || {});
+  const portalUrl = buildExternalSystemUiUrl(result.dataplaneUiBaseUrl, roleKey);
+  const caseResult = await resolveRoleAssistantCaseResult(roleKey, opts, result, verdict, portalUrl);
+
+  if (opts.json) {
+    logger.log(
+      JSON.stringify(
+        buildRoleAssistantTestEnvelope(roleKey, verdict, portalUrl, result, opts, caseResult),
+        null,
+        2
+      )
+    );
+  } else {
+    displayRoleAssistantTestSummary(roleKey, 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);
+  } catch (error) {
+    handleCommandError(error, 'role-assistant test');
+    process.exit(3);
+  }
+}
+
+function setupRoleAssistantCommands(program) {
+  const roleAssistant = program
+    .command('role-assistant')
+    .description('Role Assistant lifecycle and portal workflows');
+
+  roleAssistant
+    .command('test <roleKey>')
+    .description('Run role-assistant lifecycle checks and print portal deep link')
+    .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('-v, --verbose', 'Include full lifecycle report payload in --json output')
+    .option('-d, --debug', 'Write debug logs under role-assistant/<roleKey>/logs/')
+    .option(
+      '--publish',
+      'Publish local Role Assistant package before checks (default: use public/running worker)'
+    )
+    .option('--force', 'Force upload when --publish is set')
+    .option(
+      '--subject-user-id <id>',
+      'Subject user id for governance generate (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--subject-email <email>',
+      'Subject email for governance generate (repeatable)',
+      collectString,
+      []
+    )
+    .option(
+      '--certification-profile <profile>',
+      'Certification profile for governance generate (bronze, silver, gold, ...)',
+      'bronze'
+    )
+    .option('--json', 'Machine-readable output envelope')
+    .addHelpText('after', roleAssistantHelpAfter())
+    .action((roleKey, options, cmd) => roleAssistantTestHandler(roleKey, options, cmd));
+}
+
+module.exports = {
+  setupRoleAssistantCommands,
+  roleAssistantTestHandler,
+  runRoleAssistantTestAction,
+  normalizeRoleAssistantTestOptions,
+  buildRoleAssistantTestEnvelope,
+  computeRoleAssistantExitCode,
+  resolveRoleAssistantCaseResult
+};

package/lib/commands/upload-data-sync-finalize.js

@@ -27,7 +27,7 @@ async function finalizeUploadPublishResult(ctx, payload, options) {
     options,
     label: 'Upload data sync'
   });
-  return { ...ctx, dataSync };
+  return { ...ctx, dataSync, sidecar: ctx.sidecar || null };
 }
 
 /**
@@ -40,15 +40,16 @@ async function finishUnchangedUploadPublication(params) {
   if (!isQuietMinimalSync(options)) {
     logger.log(formatSuccessLine('Config unchanged on dataplane — upload skipped.'));
   }
-  await runUploadSidecarFollowups({
+  const sidecar = await runUploadSidecarFollowups({
     systemKey,
     options,
     payload,
     dataplaneUrl,
-    authConfig
+    authConfig,
+    environment
   });
   return finalizeUploadPublishResult(
-    { dataplaneUrl, authConfig, environment, uploadSkipped: true },
+    { dataplaneUrl, authConfig, environment, uploadSkipped: true, sidecar },
     payload,
     options
   );

package/lib/commands/upload-sidecar-followups.js

@@ -12,22 +12,123 @@ const { unwrapPublicationResult, isPublicationUnchanged } = require('../utils/ex
 const { logUploadReadinessSummary } = require('../utils/external-system-readiness-display');
 const { isQuietMinimalSync } = require('../utils/upload-sync-options');
 
+function buildRoleAssistantModel(payload) {
+  return {
+    application: payload?.application,
+    dataSources: payload?.dataSources || []
+  };
+}
+
+function buildRoleAssistantSyncContext(ctx, model) {
+  // Controller deploy env (e.g. miso) ≠ role-assistant.yaml section (dev|tst|pro).
+  const { resolveRoleAssistantSettingsEnvKey } = require('../role-assistant/knowledge-sync');
+  const raEnv = resolveRoleAssistantSettingsEnvKey(
+    (ctx.options && (ctx.options.env || ctx.options.roleAssistantEnv)) || 'dev'
+  );
+  return {
+    systemKey: ctx.systemKey,
+    dataplaneUrl: ctx.dataplaneUrl,
+    authConfig: ctx.authConfig,
+    model,
+    environment: raEnv,
+    pathOptions: ctx.options.pathOptions || {},
+    dryRun: ctx.options.dryRun === true
+  };
+}
+
+async function runGovernanceSidecar(ctx, sidecar, quietSidecar) {
+  try {
+    const { uploadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
+    const uploaded = await uploadGovernanceScenarioPacks(ctx.systemKey, ctx.dataplaneUrl, ctx.authConfig, {
+      silent: quietSidecar
+    });
+    sidecar.governance = { uploaded: Number(uploaded || 0) };
+  } catch (err) {
+    sidecar.governance = { skipped: true, reason: err.message || String(err) };
+    if (!quietSidecar) {
+      logger.log(formatWarningLine(`Governance scenario upload skipped: ${err.message}`));
+    }
+  }
+}
+
+async function runEvidenceSidecar(ctx, model, sidecar, quietSidecar) {
+  const { importRoleAssistantEvidence, logRoleAssistantEvidenceImportSummary } = require('../role-assistant/evidence-sync');
+  const result = await importRoleAssistantEvidence(buildRoleAssistantSyncContext(ctx, model));
+  sidecar.evidence = result;
+  if (!quietSidecar) {
+    logRoleAssistantEvidenceImportSummary(ctx.systemKey, result, { verbose: ctx.options.verbose === true });
+  }
+}
+
+async function runKnowledgeSidecar(ctx, model, sidecar, quietSidecar) {
+  const {
+    importRoleAssistantKnowledge,
+    logKnowledgeImportSummary,
+    pushRoleAssistantDocumentStorageSettings,
+    logDocumentStorageSettingsPushSummary
+  } = require('../role-assistant/knowledge-sync');
+  const syncCtx = buildRoleAssistantSyncContext(ctx, model);
+  try {
+    const settingsResult = await pushRoleAssistantDocumentStorageSettings(syncCtx);
+    sidecar.documentStorageSettings = settingsResult;
+    if (!quietSidecar) {
+      logDocumentStorageSettingsPushSummary(ctx.systemKey, settingsResult, {
+        verbose: ctx.options.verbose === true
+      });
+    }
+  } catch (err) {
+    sidecar.documentStorageSettings = {
+      skipped: true,
+      reason: err.message || String(err)
+    };
+    if (!quietSidecar) {
+      logger.log(
+        formatWarningLine(
+          `Knowledge document storage settings update failed: ${err.message}`
+        )
+      );
+    }
+    throw err;
+  }
+  try {
+    const result = await importRoleAssistantKnowledge(syncCtx);
+    sidecar.knowledge = result;
+    if (!quietSidecar) {
+      logKnowledgeImportSummary(ctx.systemKey, result, { verbose: ctx.options.verbose === true });
+    }
+  } catch (err) {
+    sidecar.knowledge = { skipped: true, reason: err.message || String(err) };
+    if (!quietSidecar) {
+      logger.log(formatWarningLine(`Role assistant knowledge sync skipped: ${err.message}`));
+    }
+  }
+}
+
 /**
  * Sidecar follow-ups that are independent of pipeline publish hash (scenario packs).
  * @param {Object} ctx
  * @returns {Promise<void>}
  */
 async function runUploadSidecarFollowups(ctx) {
-  const { systemKey, options, dataplaneUrl, authConfig } = ctx;
-  const quietSidecar = isQuietMinimalSync(options);
+  const sidecar = {
+    governance: null,
+    evidence: null,
+    knowledge: null,
+    documentStorageSettings: null
+  };
+  const quietSidecar = isQuietMinimalSync(ctx.options);
+  const model = buildRoleAssistantModel(ctx.payload);
+  await runGovernanceSidecar(ctx, sidecar, quietSidecar);
   try {
-    const { uploadGovernanceScenarioPacks } = require('../lifecycle/scenario-upload');
-    await uploadGovernanceScenarioPacks(systemKey, dataplaneUrl, authConfig, { silent: quietSidecar });
+    await runEvidenceSidecar(ctx, model, sidecar, quietSidecar);
   } catch (err) {
-    if (!quietSidecar) {
-      logger.log(formatWarningLine(`Governance scenario upload skipped: ${err.message}`));
+    if (err && err.evidenceSummary) {
+      sidecar.evidence = err.evidenceSummary;
     }
+    throw err;
   }
+  await runKnowledgeSidecar(ctx, model, sidecar, quietSidecar);
+  return sidecar;
 }
 
 /**
@@ -54,61 +155,57 @@ async function resolveUploadProbeData(ctx, maybeRunUploadProbeFn) {
   return { probeData: null, compact };
 }
 
+function logUploadSummary(ctx, publication, probeData) {
+  if (ctx.options.suppressSummary === true) {
+    return;
+  }
+  logUploadReadinessSummary({
+    environment: ctx.environment,
+    dataplaneUrl: ctx.dataplaneUrl,
+    systemKey: ctx.systemKey,
+    publication,
+    manifest: ctx.manifest,
+    minimal: !!ctx.options.minimal,
+    willProbe: false,
+    credentialPush: ctx.credentialPush,
+    configPush: ctx.configPush,
+    forcePublish: ctx.options.force === true,
+    probeData
+  });
+}
+
+async function runProbeAfterSummary(ctx, maybeRunUploadProbe, compact) {
+  if (ctx.options.probe && !compact) {
+    await maybeRunUploadProbe(ctx.dataplaneUrl, ctx.systemKey, ctx.authConfig, ctx.options.probeTimeout, {
+      compact: false
+    });
+  }
+}
+
+async function runSidecarAndWrap(ctx) {
+  const sidecar = await runUploadSidecarFollowups(ctx);
+  return { sidecar };
+}
+
 /**
  * @param {Object} ctx
  * @param {Function} maybeRunUploadProbe
  * @returns {Promise<void>}
  */
 async function handlePublicationAndFollowups(ctx, maybeRunUploadProbe) {
-  const {
-    systemKey,
-    options,
-    manifest,
-    payload,
-    environment,
-    dataplaneUrl,
-    authConfig,
-    rawRes,
-    credentialPush,
-    configPush
-  } = ctx;
-  const publication = unwrapPublicationResult(rawRes);
+  const publication = unwrapPublicationResult(ctx.rawRes);
   if (!publication) {
     throw new Error(
       'Unexpected response from dataplane upload: missing publication result (uploadId/system/datasources).'
     );
   }
   if (isPublicationUnchanged(publication)) {
-    await runUploadSidecarFollowups({ systemKey, options, payload, dataplaneUrl, authConfig });
-    return;
+    return runSidecarAndWrap(ctx);
   }
-
-  const suppressSummary = options.suppressSummary === true;
   const { probeData, compact } = await resolveUploadProbeData(ctx, maybeRunUploadProbe);
-
-  if (!suppressSummary) {
-    logUploadReadinessSummary({
-      environment,
-      dataplaneUrl,
-      systemKey,
-      publication,
-      manifest,
-      minimal: !!options.minimal,
-      willProbe: false,
-      credentialPush,
-      configPush,
-      forcePublish: options.force === true,
-      probeData
-    });
-  }
-
-  if (options.probe && !compact) {
-    await maybeRunUploadProbe(dataplaneUrl, systemKey, authConfig, options.probeTimeout, {
-      compact: false
-    });
-  }
-
-  await runUploadSidecarFollowups({ systemKey, options, payload, dataplaneUrl, authConfig });
+  logUploadSummary(ctx, publication, probeData);
+  await runProbeAfterSummary(ctx, maybeRunUploadProbe, compact);
+  return runSidecarAndWrap(ctx);
 }
 
 module.exports = {

package/lib/commands/upload.js

@@ -47,6 +47,12 @@ const { syncDeployJsonFromSources } = require('../external-system/sync-deploy-ma
 const { handlePublicationAndFollowups } = require('./upload-sidecar-followups');
 const { finalizeUploadPublishResult, finishUnchangedUploadPublication } = require('./upload-data-sync-finalize');
 const { pushAndLogCredentialSecrets } = require('./upload-credential-push-log');
+const {
+  SYSTEM_KIND_DIGITAL_WORKER,
+  readRoleAssistantSettings,
+  resolveRoleAssistantSettingsVersion,
+  resolveRoleAssistantEnvironmentSettings
+} = require('../role-assistant/settings');
 
 /**
  * Validates system-key format (same as download).
@@ -123,14 +129,24 @@ async function resolveDataplaneAndAuth(systemKey, opts = {}) {
  * @param {string} dataplaneUrl - Dataplane base URL
  * @param {Object} authConfig - Auth config
  * @param {Object} payload - { version, application, dataSources, status: "draft" }
+ * @param {string} systemKey
+ * @param {Object} [options]
+ * @param {number|string} [options.timeoutMs]
  * @returns {Promise<Object>} Raw API response envelope
  */
-async function runUploadValidatePublish(dataplaneUrl, authConfig, payload, systemKey) {
+async function runUploadValidatePublish(
+  dataplaneUrl,
+  authConfig,
+  payload,
+  systemKey,
+  options = {}
+) {
   const res = await uploadApplicationViaPipelineWithAuthRetry(
     dataplaneUrl,
     authConfig,
     payload,
-    systemKey
+    systemKey,
+    { timeoutMs: options.timeoutMs }
   );
   if (res?.success === false) {
     throw new Error(formatApiError(res, dataplaneUrl));
@@ -231,6 +247,14 @@ async function buildValidatedUploadManifestPayload(systemKey, opts = {}) {
     force: opts.force === true,
     status: opts.uploadStatus === 'published' ? 'published' : 'draft'
   });
+  if (String(manifest?.system?.systemKind || '').trim() === SYSTEM_KIND_DIGITAL_WORKER) {
+    const settings = readRoleAssistantSettings(systemKey, { required: true, pathOptions });
+    resolveRoleAssistantEnvironmentSettings(settings, opts.env || 'dev', { required: true });
+    const settingsVersion = resolveRoleAssistantSettingsVersion(settings);
+    if (settingsVersion) {
+      payload.version = settingsVersion;
+    }
+  }
   await resolvePayloadConfiguration(systemKey, payload, pathOptions);
   return { manifest, payload };
 }
@@ -264,7 +288,10 @@ async function logAndSyncLocalOpenApiForUpload(systemKey, manifest, uploadContex
     systemKey,
     datasourceFiles,
     dataplaneUrl: uploadContext.dataplaneUrl,
-    authConfig: uploadContext.authConfig
+    authConfig: uploadContext.authConfig,
+    // Always replace SpecFile rows keyed by openapi.documentKey so vendor/full
+    // specs are not left missing while only thin internal:* slices remain.
+    force: true
   });
   if (!uploadContext.quiet) {
     for (const line of openapiSyncLines) {
@@ -293,7 +320,7 @@ async function completeUploadAfterPublish(systemKey, options, manifest, payload,
     pathOptions: options.pathOptions,
     quiet: quietCompact
   });
-  await handlePublicationAndFollowups(
+  const followupResult = await handlePublicationAndFollowups(
     {
       systemKey,
       options,
@@ -309,7 +336,13 @@ async function completeUploadAfterPublish(systemKey, options, manifest, payload,
     maybeRunUploadProbe
   );
   return finalizeUploadPublishResult(
-    { dataplaneUrl: ctx.dataplaneUrl, authConfig: ctx.authConfig, environment: ctx.environment, uploadSkipped: false },
+    {
+      dataplaneUrl: ctx.dataplaneUrl,
+      authConfig: ctx.authConfig,
+      environment: ctx.environment,
+      uploadSkipped: false,
+      sidecar: followupResult?.sidecar || null
+    },
     payload,
     options
   );
@@ -331,7 +364,10 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
     payload
   );
   const rawRes = await runWithUploadPipelineSpinner(
-    async() => runUploadValidatePublish(dataplaneUrl, authConfig, payload, systemKey),
+    async() =>
+      runUploadValidatePublish(dataplaneUrl, authConfig, payload, systemKey, {
+        timeoutMs: options.timeoutMs
+      }),
     {
       systemKey,
       json: options.json === true,
@@ -367,6 +403,7 @@ async function runUploadPublishAndSummary(systemKey, options, manifest, payload)
  * @param {boolean} [options.verbose] - Expanded summary and server-side pipeline validate warnings
  * @param {boolean} [options.probe] - POST validation/run after publish
  * @param {number} [options.probeTimeout] - Probe timeout ms (default 120000)
+ * @param {number} [options.timeoutMs] - Pipeline publish timeout ms (HTTP + dataplane; default 300000)
  * @param {boolean} [options.minimal] - Short summary (default: compact unless --verbose)
  * @returns {Promise<{ dataplaneUrl: string, authConfig: Object, environment: string }|void>}
  * @throws {Error} If validation or API calls fail