@aifabrix/builder 2.55.2 → 2.57.0

package/lib/cli/setup-app.js

@@ -56,20 +56,21 @@ Examples:
       --client-id "$DEV_MISO_CLIENTID" \\
       --client-secret "$DEV_MISO_CLIENTSECRET"
 
-  # CI/CD — external integration (after upload/tests; promote to controller)
+  # CI/CD — external integration (qualify once via upload, then fast promote via deploy)
   $ aifabrix validate hubspot-demo
   $ aifabrix upload hubspot-demo --probe
   $ aifabrix deploy hubspot-demo --probe -v
-  # Prove pillars in tst/CI, then promote (plain deploy seals cert on published Deploy)
-  $ aifabrix deploy ek-sales --gate full --subject-email ops@example.com
   $ aifabrix deploy ek-sales
 
 Notes:
   - Login or set MISO_CONTROLLER_URL + environment (aifabrix login / aifabrix auth).
   - CI: register once (aifabrix app register <appKey>), store DEV_MISO_CLIENTID and DEV_MISO_CLIENTSECRET in pipeline secrets.
-  - upload = dataplane publish for dev iteration; deploy = controller validate + deploy (Azure or local Docker).
-  - Prove (tst/CI): use --gate full (optional --subject-email) before promote; plain deploy promotes without live E2E gates.
-  - After a successful published Deploy, the platform seals the integration certificate (no separate certificates issue step).
+  - For Connected Systems, upload validates, publishes, and finalizes the system; optional
+    checks run only with upload --gate. Deploy promotes the completed upload — the
+    server decides this automatically, no flag needed. A system that has never been uploaded
+    falls back to the full legacy ladder at deploy time instead.
+  - --gate is a no-op on deploy (kept for compatibility; prints a notice) — gates now run once
+    during "aifabrix upload", not at deploy time.
   - Default output is a compact status card; use -v for expanded preflight and readiness detail.
   - Controller deploy always polls to a terminal status (no --poll / --no-poll on this command).
   - --repository-url overrides repo URL for pipeline validate (default: application.yaml repository.repositoryUrl).

package/lib/cli/setup-environment.js

@@ -7,39 +7,95 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { isWorkspaceMode, isLegacyMarketplaceMode } = require('../deployment/installation/stage-input');
 
 /**
- * Sets up environment deployment commands
- * @param {Command} program - Commander program instance
+ * Adds installation workspace and deprecated explicit Marketplace options.
+ * @param {Command} command - Commander command
+ * @returns {Command} The command
  */
-function setupEnvironmentCommands(program) {
-  const deployEnvHandler = async(envKey, options) => {
-    try {
+function addMarketplaceOptions(command) {
+  return command
+    .option('--stage <stage>', 'Installation workspace stage: register, infra, dev, tst or pro (<env> is then the resource group)')
+    .option('--vendor <vendor>', 'Installation vendor: AZURE (default) or DOCKER (register only)')
+    .option('--allow-my-ip', 'Allow the caller public IPv4 /32 to reach PostgreSQL, Key Vault and Storage (infra only; default off)')
+    .option('--license-edition <edition>', 'License requested at activation: COMMUNITY, STANDARD, ENTERPRISE or a Marketplace subscription ID (infra only; saved in the workspace)')
+    .option('--miso-api-key-env <name>', 'Environment variable holding a temporary Miso API key (dev, tst, pro)')
+    .option('--controller-url <url>', 'Controller URL override for dev, tst or pro (deprecated platform stage also uses it)')
+    .option('--marketplace-json <file>', 'Deprecated explicit mode: ARM Marketplace infrastructure template')
+    .option('--parameters <file>', 'Deprecated explicit mode: secure ARM deploymentParameters JSON file')
+    .option('--subscription <id>', 'Deprecated explicit mode: Azure subscription ID')
+    .option('--resource-group <name>', 'Deprecated explicit mode: new isolated Azure resource group')
+    .option('--install-id <id>', 'Deprecated explicit mode: installation ID and resume-journal key')
+    .option('--location <region>', 'Deprecated explicit mode: Azure region when not set in the parameter file');
+}
+
+async function runLegacyMarketplace(envKey, options) {
+  process.stderr.write(`${formatWarningLine('Explicit Marketplace flags are deprecated; use af env deploy <resource-group> --stage infra')}\n`);
+  const installer = require('../deployment/marketplace-environment');
+  const result = await installer.deployMarketplaceEnvironment(envKey, options);
+  if (result.platformComplete) {
+    process.stdout.write(`Platform ready: ${result.publicControllerUrl}\n`);
+  } else {
+    process.stdout.write(`Infrastructure deployed: ${result.outputs.webAppUrl} (deployment ${result.deploymentId})\n`);
+    process.stdout.write(`Resume after controller login and wizard activation: af env deploy ${envKey} --install-id ${result.installId} --controller-url https://<ready-public-host>/miso --stage platform\n`);
+  }
+}
+
+async function runInstallationStage(resourceGroup, options) {
+  const { deployInstallationStage } = require('../deployment/installation');
+  const { formatStageResult } = require('../deployment/installation/stage-output');
+  const result = await deployInstallationStage(resourceGroup, options);
+  process.stdout.write(formatStageResult(result, resourceGroup));
+}
+
+async function deployEnvHandler(envKey, options) {
+  try {
+    if (isWorkspaceMode(options)) {
+      await runInstallationStage(envKey, options);
+    } else if (isLegacyMarketplaceMode(options)) {
+      await runLegacyMarketplace(envKey, options);
+    } else {
       const environmentDeploy = require('../deployment/environment');
       await environmentDeploy.deployEnvironment(envKey, options);
-    } catch (error) {
-      handleCommandError(error, 'env deploy');
-      process.exit(1);
     }
-  };
+  } catch (error) {
+    handleCommandError(error, 'env deploy');
+    process.exit(1);
+  }
+}
 
-  const deployExamples = `
+const DEPLOY_EXAMPLES = `
 Examples:
   $ aifabrix env deploy dev
   $ aifabrix env deploy tst
   $ aifabrix env deploy pro --preset m
-  $ aifabrix env deploy dev --preset xl
   $ aifabrix env deploy dev --config ./env-config.json
   $ aifabrix env deploy dev --no-poll
 
-Prerequisites: aifabrix login (device token; controller permission controller:deploy).
+Installation workspace (<env> is the resource group; files under infrastructure/<resource-group>/):
+  $ af env deploy <resource-group> --stage infra
+  $ af env deploy <resource-group> --stage infra --allow-my-ip
+  $ af env deploy <resource-group> --stage infra --license-edition ENTERPRISE
+  $ af env deploy <resource-group> --stage dev
+  $ af env deploy <resource-group> --stage pro --preset m
+  $ af env deploy <resource-group> --stage register --vendor DOCKER
+
+Vendor/stage matrix:
+  AZURE   infra, dev, tst, pro   (Mori bootstrap runs inside the Marketplace template)
+  DOCKER  register only          (deploy with aifabrix setup)
+
+Prerequisites: aifabrix login (controller permission controller:deploy); infra also needs az login.
 Environment keys: miso, dev, tst, pro. Default size preset: s (use --preset s|m|l|xl).
+Tenant activation after infra is a manual step in the Miso web application.
 Run this before aifabrix deploy <app> — the environment must exist first.`;
 
-  const ENV_GROUP_HELP_AFTER = `
+const ENV_GROUP_HELP_AFTER = `
 Examples:
   $ aifabrix env deploy dev
   $ aifabrix env deploy dev --preset m
+  $ af env deploy <resource-group> --stage infra
   $ aifabrix env deploy dev --help
 
 Typical workflow:
@@ -51,21 +107,22 @@ Subcommands:
   deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
 `;
 
+function setupEnvironmentCommands(program) {
   const env = program
     .command('env')
     .description('Miso Controller environments (primary: env deploy <env>)')
     .addHelpText('after', ENV_GROUP_HELP_AFTER);
 
-  env
+  addMarketplaceOptions(env
     .command('deploy <env>')
-    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
+    .description('Deploy environment infrastructure in Miso Controller, or an installation workspace stage with --stage')
     .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
-    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
+    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s, or the workspace file value)')
     .option('--skip-validation', 'Skip environment validation')
     .option('--poll', 'Poll for deployment status', true)
-    .option('--no-poll', 'Do not poll for status')
-    .addHelpText('after', deployExamples)
+    .option('--no-poll', 'Do not poll for status'))
+    .addHelpText('after', DEPLOY_EXAMPLES)
     .action(deployEnvHandler);
 }
 
-module.exports = { setupEnvironmentCommands };
+module.exports = { setupEnvironmentCommands, deployEnvHandler, addMarketplaceOptions };

package/lib/cli/setup-external-system-help.js

@@ -6,11 +6,18 @@
 
 const UPLOAD_HELP_AFTER = `
 Examples:
-  # Publish integration/<systemKey>/ to the dataplane (typical lab flow after validate + resolve)
+  # Upload and wait for completion
   $ aifabrix upload hubspot-demo
   $ aifabrix upload hubspot-demo -v
   $ aifabrix upload hubspot-demo --probe
-  $ aifabrix upload hubspot-demo --timeout 600000
+  $ aifabrix upload hubspot-demo --gate operations,trust
+  $ aifabrix upload hubspot-demo --gate full --subject-email user@example.com
+
+  # Queue the upload and return immediately (script/CI-friendly)
+  $ aifabrix upload hubspot-demo --no-wait
+
+  # Resume watching an existing upload job (e.g. after Ctrl-C or a closed terminal)
+  $ aifabrix upload hubspot-demo --resume <jobId>
 
   # Build and validate payload only (no API calls)
   $ aifabrix upload hubspot-demo --dry-run
@@ -25,9 +32,14 @@ Examples:
 Notes:
   - Requires login (aifabrix auth status).
   - Reads files under integration/<systemKey>/ or role-assistant/<roleKey>/ for digital workers.
+  - Upload validates, publishes, and finalizes the system. Operations, trust, and governance
+    checks are optional and run only when selected with --gate. The upload keeps running on
+    Dataplane even if this CLI process is interrupted, closed, or times out — --resume re-attaches
+    to it later, it is never re-submitted or lost.
   - Default output is a compact readiness summary; use -v for expanded detail and server-side validate warnings.
   - --probe runs dataplane runtime checks after publish (slower).
-  - --timeout sets publish budget in ms (HTTP client and dataplane); default 300000.
+  - --timeout bounds only how long this CLI waits before printing a resume hint
+    (default 1800000ms/30min); it does not stop the upload job.
   - --env selects role-assistant.yaml section (dev|tst|pro) for digital workers; default dev.
   - Role Assistant packages under role-assistant/ do not use application.yaml; upload applies settings and Evidence only.
   - test-e2e and test-integration publish local files first by default; use --no-publish on those commands to skip.

package/lib/cli/setup-external-system.js

@@ -50,7 +50,11 @@ async function handleUploadCommandAction(systemKey, options) {
     options.probeTimeout === undefined || options.probeTimeout === null
       ? 120000
       : Number(options.probeTimeout);
-  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeout);
+  // Only resolve --timeout when the caller explicitly set it; leaving it undefined otherwise
+  // lets the qualification poll fall back to its own default (30min) instead of the legacy
+  // 300000ms HTTP/dataplane-publish budget default, which no longer applies to the async path.
+  const timeoutMs =
+    options.timeout !== undefined ? resolvePipelineUploadTimeoutMs(options.timeout) : undefined;
   await upload.uploadExternalSystem(systemKey, {
     ...options,
     probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000,
@@ -101,9 +105,17 @@ function setupUploadCommand(program) {
     .option('-v, --verbose', 'Expanded upload summary and server-side pipeline validate warnings before publish')
     .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
     .option('--probe-timeout <ms>', 'Timeout for --probe (default: 120000)', '120000')
+    .option(
+      '--gate <gates>',
+      'Optional upload checks (comma-separated): operations, trust, governance, full'
+    )
+    .option(
+      '--subject-email <emails>',
+      'Subject email(s) for governance checks (comma-separated; used with --gate governance|full)'
+    )
     .option(
       '--timeout <ms>',
-      'Publish timeout in ms for HTTP and dataplane budget (default: 300000; min 5000, max 2700000)'
+      'How long this CLI waits for the upload job before printing a resume hint (default: 1800000/30min; min 5000, max 2700000). The job keeps running regardless.'
     )
     .option(
       '--force',
@@ -114,6 +126,12 @@ function setupUploadCommand(program) {
       'Role Assistant settings environment section: dev, tst, or pro (default: dev)',
       'dev'
     )
+    .option('--wait', 'Wait for the upload job to complete (default)', true)
+    .option('--no-wait', 'Return the upload job id immediately without waiting')
+    .option(
+      '--resume <jobId>',
+      'Wait for an existing upload job instead of submitting again'
+    )
     .action(async(systemKey, options) => {
       try {
         await handleUploadCommandAction(systemKey, options);
@@ -341,4 +359,4 @@ function setupExternalSystemCommands(program) {
   setupExternalSystemTestCommands(program);
 }
 
-module.exports = { setupExternalSystemCommands };
+module.exports = { setupExternalSystemCommands, handleUploadCommandAction };

package/lib/commands/agent-kit-help.js

@@ -21,9 +21,10 @@ Examples:
   $ aifabrix agent-kit install --host all --approve-all claude --yes
   $ aifabrix agent-kit update --host all --approve-all --yes
   $ aifabrix agent-kit remote create --org my-org --yes
-  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
-  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start claude
+  $ aifabrix agent-kit start codex
+  $ aifabrix agent-kit list
+  $ aifabrix agent-kit kill aifabrix-docs
   $ aifabrix agent-kit status
   $ aifabrix agent-kit validate
 `;
@@ -117,23 +118,37 @@ Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
 const START_HELP = `
 Does not install Agent Kit skills. Starts claude or codex in tmux in this git
 workspace so closing the terminal does not kill the session. Detach: Ctrl-b then
-d. --approve-all writes that app's local permission config only. --name is the
-tmux session (default: last folder, e.g. aifabrix-docs). Claude also gets
---name and --remote-control hostname-user-folder, e.g.
-builder01-dev03-aifabrix-docs. Claude --tmux is for worktrees, not this wrapper.
-That is not Claude --cloud (a separate cloud VM). Codex has no phone/web attach.
+d. The defaults enable that app's Remote Control and workspace auto-approval.
+--name is the tmux session (default: last git-root folder, e.g. aifabrix-docs).
+Claude gets --name and hostname-user-folder Remote Control. Codex uses its native
+remote-control daemon. Use --no-remote-control and/or --skip-approve-all to opt
+out. Claude --tmux is for worktrees, not this wrapper.
 
 Examples:
-  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-miso --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --remote-control --detach
   $ aifabrix agent-kit start claude
-  $ aifabrix agent-kit start claude --approve-all --yes
-  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start codex
+  $ aifabrix agent-kit start claude --name aifabrix-miso
+  $ aifabrix agent-kit start codex --no-remote-control --skip-approve-all
+  $ aifabrix agent-kit start claude --detach
   $ aifabrix agent-kit start claude --dry-run --json
 `;
 
+const LIST_HELP = `
+Lists every active tmux session visible to the current Unix user.
+
+Examples:
+  $ aifabrix agent-kit list
+  $ aifabrix agent-kit list --json
+`;
+
+const KILL_HELP = `
+Stops exactly one tmux session. Use agent-kit list to find its name.
+
+Examples:
+  $ aifabrix agent-kit kill aifabrix-miso
+  $ aifabrix agent-kit kill aifabrix-miso --json
+`;
+
 module.exports = {
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP,
@@ -145,5 +160,7 @@ module.exports = {
   INIT_HELP,
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
-  START_HELP
+  START_HELP,
+  LIST_HELP,
+  KILL_HELP
 };

package/lib/commands/agent-kit.js

@@ -1,15 +1,18 @@
-/**
- * `aifabrix agent-kit` command group.
- * @fileoverview Install, init, status, update, validate, remote create, start
- */
+/** `aifabrix agent-kit` command group. */
 
 'use strict';
 
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
-const { formatSuccessLine, formatBlockingError, formatWarningLine } = require('../utils/cli-layout-chalk');
+const {
+  formatSuccessLine,
+  formatBlockingError,
+  formatWarningLine
+} = require('../utils/cli-layout-chalk');
 const { runInstall, runUpdate } = require('../agent-kit/run');
 const { runStart } = require('../agent-kit/start');
+const { runList, runKill } = require('../agent-kit/tmux-sessions');
+const { formatSessionList, formatMissingKillName } = require('../agent-kit/session-report');
 const path = require('path');
 const { runInit, runRemoteCreate } = require('../agent-kit/init');
 const { enrichInitHostOptions, enrichInitRemoteOptions, enrichRemoteOptions, enrichApproveAllOptions } = require('../agent-kit/remote-prompts');
@@ -30,6 +33,8 @@ const {
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
   START_HELP,
+  LIST_HELP,
+  KILL_HELP,
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP
 } = require('./agent-kit-help');
@@ -110,6 +115,8 @@ function emitStartReport(json, asJson) {
   logger.log(`Session    ${json.session}`);
   if (json.remoteControlName) {
     logger.log(`Remote     ${json.remoteControlName}`);
+  } else if (json.remoteControl) {
+    logger.log('Remote     Codex Remote Control');
   }
   logger.log(`Path       ${json.path}`);
   logger.log(`Launch     ${json.launch.join(' ')}`);
@@ -124,6 +131,32 @@ function emitStartReport(json, asJson) {
   logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Ready'));
 }
 
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitListReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log(formatSessionList(json));
+}
+
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitKillReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log(formatSuccessLine(`Stopped tmux session ${json.session}`));
+}
+
 /**
  * @param {Function} runner
  * @param {object} options
@@ -159,6 +192,8 @@ function setupAgentKitCommands(program) {
   addValidateCommand(group);
   addRemoteCommand(group);
   addStartCommand(group);
+  addListCommand(group);
+  addKillCommand(group);
 }
 
 /**
@@ -387,8 +422,8 @@ async function runValidateLeaf(options) {
 function addStartCommand(group) {
   group
     .command('start <app>')
-    .description('Start Claude Code or Codex in tmux (does not install skills)')
-    .option('--approve-all', 'Write auto-approve config for this app only')
+    .description('Start Claude Code or Codex with Remote Control in named tmux')
+    .option('--approve-all', 'Write auto-approve config (default for start)')
     .option('--skip-approve-all', 'Do not write auto-approve configs')
     .option('--yes', 'Same as --approve-all')
     .option('--detach', 'Create the tmux session in the background (no attach)')
@@ -398,8 +433,10 @@ function addStartCommand(group) {
     )
     .option(
       '--remote-control',
-      'Claude Code only: same session on this PC, claude.ai/code, and the Claude mobile app'
+      'Enable native Remote Control for Claude or Codex (default)',
+      true
     )
+    .option('--no-remote-control', 'Start a local tmux-only session')
     .option('--dry-run', 'Print the launch command without starting it')
     .option('--json', 'Machine-readable output')
     .addHelpText('after', START_HELP)
@@ -414,4 +451,49 @@ function addStartCommand(group) {
     });
 }
 
+/**
+ * @param {import('commander').Command} group
+ */
+function addListCommand(group) {
+  group
+    .command('list')
+    .description('List active tmux sessions for the current user')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', LIST_HELP)
+    .action(async(options) => {
+      try {
+        emitListReport(runList(options), Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit list');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addKillCommand(group) {
+  group
+    .command('kill [name]')
+    .description('Stop one tmux session by exact name')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', KILL_HELP)
+    .action(async(name, options) => {
+      if (!name) {
+        const report = formatMissingKillName(Boolean(options.json));
+        logger.error(report.stderr);
+        if (report.stdout) logger.log(report.stdout);
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        emitKillReport(runKill({ ...options, name }), Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit kill');
+        process.exitCode = 1;
+      }
+    });
+}
+
 module.exports = { setupAgentKitCommands };

package/lib/commands/repair-datasource-auto-rbac.js

@@ -34,18 +34,14 @@ function buildRenameMap(operationMap) {
   if (!operationMap || typeof operationMap !== 'object' || Array.isArray(operationMap)) return {};
   const renameMap = {};
   for (const k of Object.keys(operationMap)) {
-    // If it's already schema-valid but contains capitals, normalize to lowercase to align
-    // with RBAC permission name restrictions (external-system schema forbids A-Z).
+    // Operation keys use the capability naming contract, which allows camelCase.
+    // RBAC permission names are normalized separately when permissions are generated.
     if (/^[a-z][a-zA-Z0-9]*$/.test(k)) {
-      if (/[A-Z]/.test(k)) {
-        renameMap[k] = k.toLowerCase();
-      }
       continue;
     }
     const camel = toCamelCaseKey(k);
     if (!camel || camel === k) continue;
-    // Use lowercase key to keep RBAC permission names schema-valid.
-    renameMap[k] = camel.toLowerCase();
+    renameMap[k] = camel;
   }
   return renameMap;
 }
@@ -212,7 +208,7 @@ function normalizeAutoRbacOperationKeys(parsed, changes) {
   if (updated && Array.isArray(changes)) {
     const pairs = keysToRename.map((k) => `${k}→${renameMap[k]}`).join(', ');
     changes.push(
-      `Normalized autoRbac operation keys (permission names are lowercase per schema; kebab aliases fold into canonical keys): ${pairs}`
+      `Normalized schema-invalid autoRbac operation aliases to camelCase keys (RBAC permission names remain lowercase): ${pairs}`
     );
   }
 
@@ -224,4 +220,3 @@ module.exports = {
   toCamelCaseKey,
   toKebabAliasKey
 };
-

package/lib/commands/upload-openapi-sync-followup.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Post-publish local OpenAPI sync follow-up, shared by the synchronous and
+ * qualification-async upload paths (extracted from upload.js per plan 191.0 file-size gate).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
+const { maybeSyncOpenApiFilesForMcp } = require('./repair-openapi-sync');
+const { exportProgrammaticOpenApiForRepair } = require('./repair-openapi-export');
+
+/**
+ * Upload local `integration/<systemKey>/openapi/*.json` specs when present so dataplane can store
+ * vendor OpenAPI keyed by each datasource `openapi.documentKey` (same behavior as repair --api OpenAPI sync).
+ * Call this **after** the external system row exists (successful publish or completed qualification):
+ * list/upload endpoints require it. First publish still succeeds because pipeline materializes
+ * internal specs from `openapi.operations` when needed.
+ *
+ * @param {string} systemKey
+ * @param {Object} manifest
+ * @param {Object} [uploadContext]
+ * @returns {Promise<void>}
+ */
+async function logAndSyncLocalOpenApiForUpload(systemKey, manifest, uploadContext = {}) {
+  const pathOptions = uploadContext.pathOptions || {};
+  const appPath = resolveExternalSystemPath(systemKey, pathOptions);
+  const ei = manifest && manifest.externalIntegration;
+  const datasourceFiles = ei && Array.isArray(ei.dataSources) ? ei.dataSources : [];
+  await exportProgrammaticOpenApiForRepair({
+    appPath,
+    systemKey,
+    datasourceFiles,
+    dryRun: false,
+    backupCtx: { dryRun: false, changedFiles: [] }
+  });
+  const openapiSyncLines = await maybeSyncOpenApiFilesForMcp({
+    enabled: true,
+    dryRun: false,
+    appPath,
+    systemKey,
+    datasourceFiles,
+    dataplaneUrl: uploadContext.dataplaneUrl,
+    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) {
+      logger.log(line.startsWith('Skipped') ? formatWarningLine(line) : formatSuccessLine(line));
+    }
+  }
+}
+
+module.exports = { logAndSyncLocalOpenApiForUpload };