@aifabrix/builder 2.49.2 → 2.50.0

package/lib/commands/run-post-publish-data-sync.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Post-publish/deploy datasource data sync hook.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveSyncPlan, executeSyncPlan } = require('./datasource-sync-policy');
+const { logDatasourceSyncSummary } = require('./datasource-sync-display');
+
+/**
+ * @param {string[]} datasourceKeys
+ * @param {Object|null|undefined} payload
+ * @returns {string[]}
+ */
+function extractDatasourceKeysFromPayload(payload, datasourceKeys) {
+  if (Array.isArray(datasourceKeys) && datasourceKeys.length > 0) {
+    return datasourceKeys;
+  }
+  const fromPayload = Array.isArray(payload?.dataSources)
+    ? payload.dataSources.map((row) => row && row.key).filter(Boolean)
+    : [];
+  return fromPayload;
+}
+
+/**
+ * @async
+ * @param {Object} params
+ * @param {string[]} [params.datasourceKeys]
+ * @param {Object} [params.payload]
+ * @param {string} params.dataplaneUrl
+ * @param {Object} params.authConfig
+ * @param {Object} [params.options]
+ * @param {string} [params.label]
+ * @returns {Promise<Object|null>}
+ */
+async function runPostPublishDataSync(params) {
+  const { dataplaneUrl, authConfig, payload, options = {}, label } = params;
+  if (!dataplaneUrl || !authConfig || options.dryRun === true || options.skipDataSync === true) {
+    return null;
+  }
+
+  const keys = extractDatasourceKeysFromPayload(payload, params.datasourceKeys);
+  if (keys.length === 0) {
+    return null;
+  }
+
+  const plan = await resolveSyncPlan({
+    syncExplicit: options.sync === true,
+    skipSync: options.skipDataSync === true,
+    datasourceKeys: keys,
+    dataplaneUrl,
+    authConfig
+  });
+  const result = await executeSyncPlan(plan, dataplaneUrl, authConfig);
+  logDatasourceSyncSummary(result, {
+    json: options.json === true,
+    label,
+    syncExplicit: options.sync === true
+  });
+  return result;
+}
+
+module.exports = {
+  runPostPublishDataSync,
+  extractDatasourceKeysFromPayload
+};

package/lib/commands/setup-modes.js

@@ -58,7 +58,7 @@ const {
 } = require('../utils/infra-optional-service-flags');
 
 /** Builder app keys touched by `up-platform --force`. */
-const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane'];
+const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane', 'builder-api'];
 
 function formatBackupSuffix() {
   const d = new Date();

package/lib/commands/test-e2e-external.js

@@ -13,12 +13,12 @@ const path = require('path');
 const fs = require('fs');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { getIntegrationPath } = require('../utils/paths');
+const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile } = require('../utils/config-format');
 const { discoverIntegrationFiles, buildEffectiveDatasourceFiles } = require('./repair-internal');
 const { runDatasourceTestE2E } = require('../datasource/test-e2e');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 const { buildMinimalUploadSyncOptions, isQuietMinimalSync } = require('../utils/upload-sync-options');
 const { getConfig } = require('../core/config');
 const { setupIntegrationTestAuth } = require('../external-system/test-auth');
@@ -90,15 +90,26 @@ function getDatasourceKeys(appPath, configPath, variables, systemKey, systemPars
 
 /**
  * Publish local integration files to the dataplane before E2E (same path as `aifabrix upload <systemKey>`),
- * unless ``options.noSync`` is true.
+ * unless ``options.noPublish`` is true.
  * @param {string} systemKey
  * @param {Object} options
  * @returns {Promise<{ authConfig: Object, dataplaneUrl: string, environment?: string }|null>}
  */
 async function syncLocalIfRequested(systemKey, options) {
-  if (cliOptsSkipSync(options)) return null;
+  if (cliOptsSkipPublish(options)) return null;
   const { uploadExternalSystem } = require('./upload');
-  const uploadOpts = buildMinimalUploadSyncOptions(options);
+  const uploadOpts = {
+    ...buildMinimalUploadSyncOptions(options),
+    uploadStatus: options.uploadStatus === 'published' ? 'published' : 'draft',
+    pathOptions: {},
+    ...(options.authConfig && options.dataplaneUrl
+      ? {
+        authConfig: options.authConfig,
+        dataplaneUrl: options.dataplaneUrl,
+        environment: options.environment
+      }
+      : {})
+  };
   const uploadCtx = await uploadExternalSystem(systemKey, uploadOpts);
   if (uploadCtx?.uploadSkipped !== true && !isQuietMinimalSync(uploadOpts)) {
     logger.log(formatSuccessLine('Sync complete'));
@@ -117,7 +128,7 @@ async function syncLocalIfRequested(systemKey, options) {
  * @param {boolean} [options.debug] - Include debug, write log
  * @param {boolean} [options.verbose] - Verbose output
  * @param {boolean} [options.async] - If false, sync mode (default true)
- * @param {boolean} [options.noSync] - When true, skip upload (E2E uses dataplane config already deployed)
+ * @param {boolean} [options.noPublish] - When true, skip upload (E2E uses dataplane config already deployed)
  * @returns {Promise<{ success: boolean, results: Array<{ key: string, success: boolean, error?: string }> }>}
  */
 /**
@@ -125,11 +136,11 @@ async function syncLocalIfRequested(systemKey, options) {
  * @param {string} externalSystem
  * @returns {{ systemKey: string, keys: string[] }}
  */
-function resolveExternalIntegrationContext(externalSystem) {
+function resolveExternalIntegrationContext(externalSystem, pathOptions = {}) {
   if (!externalSystem || typeof externalSystem !== 'string') {
     throw new Error('External system name is required');
   }
-  const appPath = getIntegrationPath(externalSystem);
+  const appPath = resolveExternalSystemPath(externalSystem, pathOptions);
   if (!fs.existsSync(appPath)) {
     throw new Error(`Integration path not found: ${appPath}`);
   }
@@ -199,6 +210,8 @@ async function runTestE2EForExternalSystem(externalSystem, options = {}) {
     debug: options.debug,
     verbose: options.verbose,
     async: options.async !== false,
+    version: options.version,
+    syncMode: options.syncMode,
     authConfig,
     dataplaneUrl,
     quietPollUi: options.quietPollUi === true,

package/lib/commands/test-governance-cli-options.js

@@ -6,7 +6,7 @@
 
 'use strict';
 
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
 /**
  * @param {string[]} [raw]
@@ -34,7 +34,7 @@ function normalizeTestGovernanceCliOptions(options, cmd) {
     env: options.env || 'dev',
     verbose: options.verbose === true || has('-v') || has('--verbose'),
     json: options.json === true || has('--json'),
-    noSync: cliOptsSkipSync(options, cmd),
+    noPublish: cliOptsSkipPublish(options, cmd),
     pack: options.pack,
     app: options.app,
     scenarioIds: collectScenarioIds(options.scenario)

package/lib/commands/test-trust-cli-options.js

@@ -4,7 +4,7 @@
 
 'use strict';
 
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
 /**
  * @param {Object} options - Commander-parsed options
@@ -19,7 +19,7 @@ function normalizeTestTrustCliOptions(options, cmd) {
     debug: options.debug === true || has('-d') || has('--debug'),
     verbose: options.verbose === true || has('-v') || has('--verbose'),
     revalidate: options.revalidate === true || has('--revalidate'),
-    noSync: cliOptsSkipSync(options, cmd),
+    noPublish: cliOptsSkipPublish(options, cmd),
     strict: options.strict === true || has('--strict'),
     summary: options.summary === true || has('--summary'),
     json: options.json === true || has('--json'),

package/lib/commands/up-builder-api-bootstrap.js

@@ -0,0 +1,71 @@
+/**
+ * Headless builder-api bootstrap provisioning (plan 154.2 / 197 pattern).
+ *
+ * @fileoverview up-builder-api bootstrap path when Docker + ENCRYPTION_KEY available
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { callBootstrapApi } = require('../utils/app-bootstrap-api');
+const {
+  loadVariablesYaml,
+  extractAppConfiguration
+} = require('../utils/app-register-config');
+const { buildRegistrationData, saveLocalCredentials, applyLocalhostPortAdjustment } = require('../app/register');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { resolveBootstrapEncryptionKey } = require('./up-dataplane-bootstrap');
+
+/**
+ * Register builder-api via bootstrap endpoint (idempotent).
+ * @async
+ * @param {Object} options - up-builder-api options
+ * @param {string} controllerUrl
+ * @param {string} environmentKey
+ * @param {Function} buildBuilderApiImageRefFn
+ * @returns {Promise<void>}
+ */
+async function bootstrapBuilderApiApplication(options, controllerUrl, environmentKey, buildBuilderApiImageRefFn) {
+  const encryptionKey = await resolveBootstrapEncryptionKey();
+  if (!encryptionKey) {
+    throw new Error(
+      'Bootstrap encryption key is not available. Ensure miso-controller-secrets-encryptionKeyVault ' +
+        'exists in merged secrets after up-miso resolve.'
+    );
+  }
+
+  const { variables } = await loadVariablesYaml('builder-api');
+  const appConfig = await extractAppConfiguration(variables, 'builder-api', options);
+  await applyLocalhostPortAdjustment(appConfig, controllerUrl, options);
+
+  const imageOverride = options.image || buildBuilderApiImageRefFn(options);
+  const registerOpts = {
+    imageOverride,
+    image: imageOverride,
+    registryMode: options.registryMode,
+    envKey: environmentKey
+  };
+  const registrationData = buildRegistrationData(appConfig, registerOpts);
+
+  logger.log(chalk.blue('Provisioning builder-api via bootstrap (no device login)...'));
+  const responseData = await callBootstrapApi(
+    controllerUrl,
+    encryptionKey,
+    environmentKey,
+    registrationData
+  );
+
+  if (responseData.credentials && responseData.credentials.clientSecret) {
+    await saveLocalCredentials(responseData, controllerUrl);
+    logger.log(formatSuccessLine('Builder-api bootstrap credentials saved locally'));
+  } else if (responseData.status === 'already_provisioned') {
+    logger.log(formatSuccessLine('Builder-api already provisioned (bootstrap idempotent)'));
+  }
+}
+
+module.exports = {
+  bootstrapBuilderApiApplication
+};

package/lib/commands/up-builder-api-provision.js

@@ -0,0 +1,241 @@
+/**
+ * Register, deploy, and env refresh for builder-api (plan 154.2).
+ *
+ * @fileoverview Shared provision helpers for up-builder-api
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const pathsUtil = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
+const { resolveDockerImageRef, normalizeDockerRegistryPrefix } = require('../utils/resolve-docker-image-ref');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const { checkAuthentication } = require('../utils/app-register-auth');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveEnvironment } = require('../core/config');
+const { registerApplication } = require('../app/register');
+const { rotateSecret } = require('../app/rotate-secret');
+const { checkApplicationExists } = require('../utils/app-existence');
+const { checkHealthEndpoint } = require('../utils/health-check');
+const app = require('../app');
+const { assertDevInfraUp } = require('./dev-infra-gate');
+const { publishedHostPort, parseDeveloperIdNum } = require('../utils/declarative-url-ports');
+const { canUseBootstrapProvision } = require('./up-dataplane-bootstrap');
+const { bootstrapBuilderApiApplication } = require('./up-builder-api-bootstrap');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { generateEnvFile } = require('../core/secrets');
+
+const CONTROLLER_HEALTH_PATH = '/health';
+const CONTROLLER_HEALTH_RETRY_ATTEMPTS = 30;
+const CONTROLLER_HEALTH_RETRY_DELAY_MS = 2000;
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {string} baseUrl
+ * @returns {Promise<boolean>}
+ */
+async function isControllerHealthy(baseUrl) {
+  const healthUrl = `${baseUrl.replace(/\/+$/, '')}${CONTROLLER_HEALTH_PATH}`;
+  try {
+    return await checkHealthEndpoint(healthUrl, false);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {{ attempts?: number, delayMs?: number }} [opts]
+ * @returns {Promise<boolean>}
+ */
+async function waitForControllerHealthy(baseUrl, opts = {}) {
+  const attempts = opts.attempts ?? CONTROLLER_HEALTH_RETRY_ATTEMPTS;
+  const delayMs = opts.delayMs ?? CONTROLLER_HEALTH_RETRY_DELAY_MS;
+  const normalized = baseUrl.replace(/\/+$/, '');
+  for (let i = 0; i < attempts; i += 1) {
+    if (await isControllerHealthy(normalized)) {
+      return true;
+    }
+    if (i < attempts - 1) {
+      await sleep(delayMs);
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {Object} [options]
+ * @returns {string|undefined}
+ */
+function buildBuilderApiImageRef(options = {}) {
+  try {
+    const builderPath = pathsUtil.getBuilderPath('builder-api');
+    const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+    const variables = loadConfigFile(configPath) || {};
+    const cli = normalizeDockerRegistryPrefix(options.registry);
+    const manifestReg = normalizeDockerRegistryPrefix(variables.image?.registry);
+    if (!cli && !manifestReg) {
+      return undefined;
+    }
+    const { imageName, imageTag } = resolveDockerImageRef('builder-api', variables, {
+      registry: options.registry || undefined
+    });
+    return `${imageName}:${imageTag}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {Object} cfg
+ */
+function assertDevEnvironmentForBuilderApi(cfg) {
+  const environment = cfg && cfg.environment ? cfg.environment : 'dev';
+  if (environment !== 'dev') {
+    throw new Error(
+      'Builder-api is only supported in dev environment. Set with: aifabrix auth --set-environment dev.'
+    );
+  }
+}
+
+/**
+ * @async
+ * @param {Object} options
+ * @returns {Promise<string>}
+ */
+async function prepareHealthyControllerUrl(options) {
+  if (options.skipInfraCheck !== true) {
+    await assertDevInfraUp();
+  }
+  let controllerUrl = await resolveControllerUrl();
+  controllerUrl = controllerUrl.replace(/\/+$/, '');
+  const healthy = await waitForControllerHealthy(controllerUrl);
+  if (!healthy) {
+    throw new Error(`Controller at ${controllerUrl} is not responding. Ensure miso-controller is running.`);
+  }
+  return controllerUrl;
+}
+
+/**
+ * @async
+ * @param {Object} options
+ * @param {string} environmentKey
+ * @returns {Promise<{ controllerUrl: string, authConfig: Object|null, useBootstrap: boolean }>}
+ */
+async function resolveUpBuilderApiControllerContext(options, environmentKey) {
+  const useBootstrap = await canUseBootstrapProvision(options);
+  const controllerUrl = await prepareHealthyControllerUrl(options);
+  const cfg = await config.getConfig();
+  if (options.allowNonDev !== true) {
+    assertDevEnvironmentForBuilderApi(cfg);
+  }
+  if (useBootstrap) {
+    if (options.platformInstall !== true) {
+      logger.log(formatSuccessLine('Using bootstrap provision (no device login)'));
+    }
+    return { controllerUrl, authConfig: null, useBootstrap: true };
+  }
+  const authConfig = await checkAuthentication(controllerUrl, environmentKey, { throwOnFailure: true });
+  if (options.platformInstall !== true) {
+    logger.log(formatSuccessLine(`Logged in (environment: ${environmentKey})`));
+  }
+  return { controllerUrl, authConfig, useBootstrap: false };
+}
+
+/**
+ * @async
+ */
+async function registerOrRotateBuilderApi(options, controllerUrl, environmentKey, authConfig) {
+  const appExists = await checkApplicationExists('builder-api', controllerUrl, environmentKey, authConfig);
+  if (appExists) {
+    logger.log(chalk.blue('Builder-api already registered; rotating secret...'));
+    await rotateSecret('builder-api', options);
+    return;
+  }
+  const imageOverride = options.image || buildBuilderApiImageRef(options);
+  await registerApplication('builder-api', {
+    imageOverride,
+    image: imageOverride,
+    registryMode: options.registryMode,
+    envKey: environmentKey
+  });
+}
+
+/**
+ * @async
+ */
+async function deployBuilderApiToController(options) {
+  const imageOverride = options.image || buildBuilderApiImageRef(options);
+  await app.deployApp('builder-api', {
+    imageOverride,
+    image: imageOverride,
+    registryMode: options.registryMode,
+    envKey: options.envKey ? String(options.envKey).trim().toLowerCase() : undefined,
+    silentPoll: options.platformInstall === true
+  });
+}
+
+/**
+ * @async
+ */
+async function provisionAndDeployBuilderApi(options, environmentKey, controllerUrl, useBootstrap, authConfig) {
+  if (useBootstrap) {
+    await bootstrapBuilderApiApplication(options, controllerUrl, environmentKey, buildBuilderApiImageRef);
+  } else {
+    await registerOrRotateBuilderApi(options, controllerUrl, environmentKey, authConfig);
+  }
+
+  await deployBuilderApiToController({
+    ...options,
+    envKey: environmentKey,
+    ...(useBootstrap ? { deploymentAuth: 'client-credentials' } : {})
+  });
+  logger.log('');
+}
+
+/**
+ * Materialize builder-api .env after bootstrap/register so run uses fresh MISO_* credentials.
+ * @async
+ */
+async function refreshBuilderApiEnvAfterProvision() {
+  try {
+    await generateEnvFile('builder-api', null, 'local', true);
+    logger.log(formatSuccessLine('Refreshed builder-api .env from resolved secrets'));
+  } catch (error) {
+    logger.warn(chalk.yellow(`Could not refresh builder-api .env: ${error.message}`));
+  }
+}
+
+/**
+ * @async
+ */
+async function computeBuilderApiRunOverrides(options) {
+  const runEnvKey = options.runEnvKey ? String(options.runEnvKey).trim().toLowerCase() : undefined;
+  const developerIdRaw = await config.getDeveloperId();
+  const developerIdNum = parseDeveloperIdNum(developerIdRaw);
+  if (runEnvKey && runEnvKey !== 'dev' && runEnvKey !== 'tst') {
+    return { runEnvKey, portOverride: undefined };
+  }
+  const portOverride = publishedHostPort(3005, developerIdNum);
+  return { runEnvKey, portOverride };
+}
+
+module.exports = {
+  buildBuilderApiImageRef,
+  resolveUpBuilderApiControllerContext,
+  provisionAndDeployBuilderApi,
+  refreshBuilderApiEnvAfterProvision,
+  computeBuilderApiRunOverrides,
+  resolveEnvironment
+};

package/lib/commands/up-builder-api.js

@@ -0,0 +1,88 @@
+const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
+/**
+ * AI Fabrix Builder - Up Builder API Command
+ *
+ * Materializes builder-api from template, registers via bootstrap or device login,
+ * deploys manifest to controller, and runs locally (plan 154.2).
+ *
+ * @fileoverview up-builder-api command implementation
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const app = require('../app');
+const {
+  ensureBuilderApiAppsFromTemplate,
+  patchEnvOutputPathForDeployOnly,
+  validateEnvOutputPathFolderOrNull,
+  refreshUrlsLocalRegistryForCurrentProject
+} = require('./up-common');
+const {
+  resolveUpBuilderApiControllerContext,
+  provisionAndDeployBuilderApi,
+  refreshBuilderApiEnvAfterProvision,
+  computeBuilderApiRunOverrides,
+  resolveEnvironment
+} = require('./up-builder-api-provision');
+
+/**
+ * @async
+ * @param {Object} [options]
+ * @returns {Promise<void>}
+ */
+async function handleUpBuilderApi(options = {}) {
+  if (options.platformInstall !== true) {
+    logger.log(
+      chalk.blue('Starting up-builder-api (bootstrap/register, deploy, then run builder-api locally)...\n')
+    );
+  }
+
+  const environmentKey =
+    options && options.envKey
+      ? String(options.envKey).trim().toLowerCase()
+      : await resolveEnvironment();
+
+  const { controllerUrl, authConfig, useBootstrap } = await resolveUpBuilderApiControllerContext(
+    options,
+    environmentKey
+  );
+
+  await ensureBuilderApiAppsFromTemplate({ silent: options.platformInstall === true });
+  validateEnvOutputPathFolderOrNull('builder-api');
+  patchEnvOutputPathForDeployOnly('builder-api');
+  refreshUrlsLocalRegistryForCurrentProject();
+
+  const { emitSystemBuilderAppManifestLineIfTTY } = require('../utils/manifest-source-emit');
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'builder-api');
+
+  await provisionAndDeployBuilderApi(options, environmentKey, controllerUrl, useBootstrap, authConfig);
+  await refreshBuilderApiEnvAfterProvision();
+
+  const { portOverride } = await computeBuilderApiRunOverrides(options);
+
+  const runOpts = {
+    registry: options.registry,
+    registryMode: options.registryMode,
+    skipEnvOutputPath: true,
+    skipInfraCheck: true,
+    skipManifestMetadataLine: true,
+    ...(portOverride !== undefined ? { port: portOverride } : {}),
+    ...(options.platformInstall === true ? { silentPoll: true } : {})
+  };
+  if (options.image) {
+    runOpts.image = options.image;
+  }
+  await app.runApp('builder-api', runOpts);
+
+  if (options.platformInstall !== true) {
+    logger.log(
+      formatSuccessParagraph(
+        'up-builder-api complete. Builder-api is registered, deployed in dev, and running locally.'
+      )
+    );
+  }
+}
+
+module.exports = { handleUpBuilderApi };

package/lib/commands/up-common.js

@@ -328,11 +328,15 @@ async function ensureAppFromTemplate(appName, opts = {}) {
 /** Dataplane app key materialized for dataplane install (worker/beat are compose sidecars). */
 const DATAPLANE_BUILDER_APP_KEYS = Object.freeze(['dataplane']);
 
+/** Builder API platform app key (154.2). */
+const BUILDER_API_APP_KEYS = Object.freeze(['builder-api']);
+
 /** Builder dirs removed on up-platform / setup force (includes Celery companions). */
 const PLATFORM_BUILDER_CLEAN_APP_KEYS = Object.freeze([
   'keycloak',
   'miso-controller',
-  ...DATAPLANE_BUILDER_APP_KEYS
+  ...DATAPLANE_BUILDER_APP_KEYS,
+  ...BUILDER_API_APP_KEYS
 ]);
 
 /**
@@ -354,6 +358,23 @@ async function ensureDataplaneAppsFromTemplate(opts = {}) {
   return anyCopied;
 }
 
+/**
+ * Ensure builder-api manifest exists under the system builder root.
+ *
+ * @param {object} [opts]
+ * @returns {Promise<boolean>}
+ */
+async function ensureBuilderApiAppsFromTemplate(opts = {}) {
+  let anyCopied = false;
+  for (const appName of BUILDER_API_APP_KEYS) {
+    const copied = await ensureAppFromTemplate(appName, opts);
+    if (copied) {
+      anyCopied = true;
+    }
+  }
+  return anyCopied;
+}
+
 /**
  * Merge builder/packages `application.yaml` into `~/.aifabrix/urls.local.yaml`.
  * Same scan as the end of {@link prepareUrlsLocalRegistryForUpPlatform}; call after platform app
@@ -381,15 +402,18 @@ async function prepareUrlsLocalRegistryForUpPlatform(opts = {}) {
   await ensureAppFromTemplate('keycloak', templateOpts);
   await ensureAppFromTemplate('miso-controller', templateOpts);
   await ensureDataplaneAppsFromTemplate(templateOpts);
+  await ensureBuilderApiAppsFromTemplate(templateOpts);
   refreshUrlsLocalRegistryForCurrentProject();
 }
 
 module.exports = {
   applyUpPlatformForceConfig,
   cleanBuilderAppDirs,
+  BUILDER_API_APP_KEYS,
   DATAPLANE_BUILDER_APP_KEYS,
   PLATFORM_BUILDER_CLEAN_APP_KEYS,
   ensureAppFromTemplate,
+  ensureBuilderApiAppsFromTemplate,
   ensureDataplaneAppsFromTemplate,
   patchEnvOutputPathForDeployOnly,
   validateEnvOutputPathFolderOrNull,