@aifabrix/builder 2.60.0 → 2.62.0

package/lib/api/system-secrets.api.js

@@ -0,0 +1,72 @@
+/**
+ * System secrets API (Miso Controller).
+ *
+ * Deliberately narrow: a value can be written and never read back, and only against a
+ * catalog key the installation already defines. There is no create endpoint, so this module
+ * must not grow one — a key that does not exist is a catalog change in aifabrix-miso, not
+ * something the CLI can fix.
+ *
+ * The PUT request body marks `value` as writeOnly. Nothing here returns a value, and no
+ * caller should construct a response shape that could carry one.
+ *
+ * @fileoverview System secrets API functions (put-only over catalog keys)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+/**
+ * @param {string} envKey - Environment key
+ * @returns {string} Collection endpoint for that environment
+ */
+function systemSecretsEndpoint(envKey) {
+  return `/api/v1/environments/${encodeURIComponent(envKey)}/system-secrets`;
+}
+
+/**
+ * Set one system secret value. The value is write-only: it cannot be read back, and this
+ * function returns the server response unchanged without echoing what was sent.
+ *
+ * PUT /api/v1/environments/{envKey}/system-secrets/{catalogKey}
+ * @requiresPermission {Miso} controller:admin
+ * @async
+ * @function putSystemSecret
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} catalogKey - Catalog key the installation already defines
+ * @param {string} value - Secret value, read from a file by the caller
+ * @param {string} revision - Opaque revision returned by the configuration list
+ * @returns {Promise<Object>} Server response; carries no value
+ * @throws {Error} If the request fails. The message must never include the value
+ */
+async function putSystemSecret(controllerUrl, authConfig, envKey, catalogKey, value, revision) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  if (!envKey || typeof envKey !== 'string') {
+    throw new Error('envKey is required and must be a string');
+  }
+  if (!catalogKey || typeof catalogKey !== 'string') {
+    throw new Error('catalogKey is required and must be a string');
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    // Names the key, never the value, because this message reaches the terminal.
+    throw new Error(`No value supplied for ${catalogKey}`);
+  }
+  if (!revision || typeof revision !== 'string') {
+    throw new Error(`No configuration revision supplied for ${catalogKey}`);
+  }
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.put(`${systemSecretsEndpoint(envKey)}/${encodeURIComponent(catalogKey)}`, {
+    body: { value },
+    headers: { 'If-Match': revision }
+  });
+}
+
+module.exports = {
+  putSystemSecret
+};

package/lib/app/deploy.js

@@ -191,12 +191,21 @@ async function handleDeploymentError(error, appName, controllerUrl, usedExternal
  * @throws {Error} If image is missing or has no registry
  */
 function validateImageIsPullable(imageRef, appName) {
-  if (!imageRef || !imageRef.includes('/')) {
-    const hint = `Set image.registry and image.tag in builder/${appName}/application.yaml, or pass a full image ref (e.g. --image <registry>/${appName}:<tag>) when deploying`;
-    throw new Error(
-      `Deployed image must be pullable (include a registry). Current image: "${imageRef || 'none'}". ${hint}`
-    );
+  if (imageRef && imageRef.includes('/')) {
+    return;
+  }
+  // No registry configured means the installation deploys the application.yaml image as it
+  // stands, from the local Docker daemon. Demanding a registry component here would make a
+  // local install impossible for the one case it is meant to serve. A configured registry
+  // still has to appear in the reference, because then the image is expected to be pullable.
+  const { readInstallationRegistrySync } = require('../utils/config-registry-preference');
+  if (!readInstallationRegistrySync()) {
+    return;
   }
+  const hint = `Set image.registry and image.tag in builder/${appName}/application.yaml, or pass a full image ref (e.g. --image <registry>/${appName}:<tag>) when deploying`;
+  throw new Error(
+    `Deployed image must be pullable (include a registry). Current image: "${imageRef || 'none'}". ${hint}`
+  );
 }
 
 /**

package/lib/app/run-docker-fallback.js

@@ -8,6 +8,8 @@
 'use strict';
 
 const chalk = require('chalk');
+const { prepareLocalDataMount } = require('../utils/prepare-local-data-mount');
+const { resolveLocalDataMountPathForCompose } = require('../utils/compose-generate-docker-compose');
 const logger = require('../utils/logger');
 const { execWithDockerEnv } = require('../utils/docker-exec');
 const { getContainerPort } = require('../utils/port-resolver');
@@ -87,7 +89,10 @@ async function executeDockerRunUp(o) {
   ];
 
   if (needsStorage) {
-    parts.push(`-v ${shellSingleQuote(storageVolumeName(appName, appConfig.developerId))}:/mnt/data`);
+    const localPath = resolveLocalDataMountPathForCompose({ appName, appConfig });
+    if (localPath) prepareLocalDataMount(localPath, runEnvPath);
+    const source = localPath || storageVolumeName(appName, appConfig.developerId);
+    parts.push(`-v ${shellSingleQuote(source)}:/mnt/data`);
   }
   if (runEnvPath && typeof runEnvPath === 'string') {
     parts.push(`--env-file ${shellSingleQuote(runEnvPath)}`);

package/lib/app/run-env-compose.js

@@ -13,6 +13,7 @@ const path = require('path');
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const pathsUtil = require('../utils/paths');
+const { isScopeActiveForOptions } = require('../utils/environment-scoped-resources');
 const adminSecrets = require('../core/admin-secrets');
 const config = require('../core/config');
 const secretsEnsure = require('../core/secrets-ensure');
@@ -25,8 +26,8 @@ const { applyAdminSecretsPlatformOverlay } = require('../core/admin-secrets-env-
  * @param {Object.<string, string>} merged
  * @param {Object.<string, string>} adminObj
  */
-function mergeRunEnvWithAdminOverlay(merged, adminObj) {
-  applyAdminSecretsPlatformOverlay(merged, adminObj);
+function mergeRunEnvWithAdminOverlay(merged, adminObj, appName) {
+  applyAdminSecretsPlatformOverlay(merged, adminObj, appName);
 }
 
 async function applyOnboardingPlatformModeIfNeeded(appName, merged) {
@@ -108,9 +109,7 @@ function injectDatabaseNamesAndUsers(env, appConfig, scopeOpts = null) {
   if (!Array.isArray(databases) || databases.length === 0) return;
   const prefix =
     scopeOpts &&
-    scopeOpts.effectiveEnvironmentScopedResources &&
-    scopeOpts.runEnvKey &&
-    (scopeOpts.runEnvKey === 'dev' || scopeOpts.runEnvKey === 'tst')
+    isScopeActiveForOptions(scopeOpts)
       ? `${String(scopeOpts.runEnvKey).toLowerCase()}-`
       : '';
   for (let i = 0; i < databases.length; i++) {
@@ -298,7 +297,7 @@ async function buildMergedRunEnvAndWrite(appName, appConfig, devDir, developerId
     runEnvKey
   });
   const merged = { ...adminObj, ...appObj };
-  mergeRunEnvWithAdminOverlay(merged, adminObj);
+  mergeRunEnvWithAdminOverlay(merged, adminObj, appName);
   await applyOnboardingPlatformModeIfNeeded(appName, merged);
   await applyPostgresPasswordFromPgpass(merged, developerId);
   injectDatabaseNamesAndUsers(merged, appConfig, scopeOpts);

package/lib/app/run-helpers.js

@@ -368,6 +368,8 @@ async function prepareEnvironment(appName, appConfig, options) {
     developerId,
     { runEnvKey, effectiveEnvironmentScopedResources }
   );
+  const { hydrateMissingLocalParameters } = require('./run-parameter-sync');
+  await hydrateMissingLocalParameters(appName, runEnvPath);
 
   const composeOptions = {
     ...options,
@@ -438,4 +440,3 @@ module.exports = {
   displayRunStatus,
   cleanApplicationsDir: runEnvCompose.cleanApplicationsDir
 };
-

package/lib/app/run-parameter-sync.js

@@ -0,0 +1,142 @@
+/**
+ * Hydrate missing application-owned parameters before a local governed run.
+ *
+ * Local/database controllers deliberately leave database generators to Builder. In
+ * client-credentials mode the application cannot start until those values are in its
+ * bootstrap snapshot, so Builder fills only unresolved declared rows through the
+ * application's own client token. Existing Controller values are never overwritten.
+ *
+ * @fileoverview Local run parameter hydration for governed bootstrap
+ */
+
+'use strict';
+
+const fs = require('fs').promises;
+const path = require('path');
+const { ApiClient } = require('../api');
+const { getToken } = require('../api/auth.api');
+const { getControllerDeploymentType } = require('../api/controller-health.api');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getBuilderPath } = require('../utils/paths');
+const { mapEnvToCatalogKeys, parseEnvAssignments } = require('../utils/system-secret-mapping');
+const { getInfraParameterCatalog } = require('../parameters/infra-parameter-catalog');
+
+const LOCAL_DEPLOYMENTS = new Set(['local', 'database']);
+const IDENTITY_NAMES = new Set([
+  'MISO_CLIENTID',
+  'MISO_CLIENT_ID',
+  'MISO_CLIENTSECRET',
+  'MISO_CLIENT_SECRET'
+]);
+
+function statusOf(response) {
+  const value = response && (response.status || response.statusCode || response.response?.status);
+  return Number.isInteger(value) ? value : 0;
+}
+
+function failed(response) {
+  return Boolean(response && (response.success === false || statusOf(response) >= 400));
+}
+
+function tokenFrom(response) {
+  const body = response && response.data !== undefined ? response.data : response;
+  const payload = body && body.data !== undefined ? body.data : body;
+  const token = payload && payload.token;
+  if (!token || typeof token !== 'string') {
+    throw new Error('Controller client-token response is invalid');
+  }
+  return token;
+}
+
+function credentialPair(env) {
+  const clientId = env.get('MISO_CLIENTID') || env.get('MISO_CLIENT_ID');
+  const clientSecret = env.get('MISO_CLIENTSECRET') || env.get('MISO_CLIENT_SECRET');
+  if (!clientId || !clientSecret) {
+    throw new Error('MISO client credentials are required for governed local configuration');
+  }
+  return { clientId, clientSecret };
+}
+
+function uniqueRows(mapping, catalog = getInfraParameterCatalog()) {
+  const rows = new Map();
+  for (const row of mapping.pushable) {
+    if (IDENTITY_NAMES.has(row.name)) continue;
+    const generatorType = catalog.findEntryForKey(row.catalogKey)?.generator?.type;
+    if (generatorType !== 'databaseUrl' && generatorType !== 'databasePassword') continue;
+    const prior = rows.get(row.catalogKey);
+    if (prior && prior.value !== row.value) {
+      throw new Error(`Conflicting local values resolve to parameter '${row.catalogKey}'`);
+    }
+    rows.set(row.catalogKey, row);
+  }
+  return [...rows.values()];
+}
+
+async function isMissing(client, key) {
+  const response = await client.get(`/api/v1/parameters/${encodeURIComponent(key)}`);
+  if (!failed(response)) return false;
+  if (statusOf(response) === 404) return true;
+  throw new Error(`Unable to inspect governed parameter '${key}'`);
+}
+
+async function writeMissing(client, row) {
+  const response = await client.put(`/api/v1/parameters/${encodeURIComponent(row.catalogKey)}`, {
+    body: { value: row.value }
+  });
+  if (failed(response)) {
+    throw new Error(`Unable to initialize governed parameter '${row.catalogKey}'`);
+  }
+}
+
+async function resolveSyncContext(appName, runEnvPath, deps) {
+  const readFile = deps.readFile || fs.readFile;
+  const envContent = await readFile(runEnvPath, 'utf8');
+  const env = parseEnvAssignments(envContent);
+  if (env.get('MISO_AUTH_MODE') !== 'client-credentials') return null;
+  const controllerUrl = await (deps.resolveControllerUrl || resolveControllerUrl)();
+  if (!controllerUrl) throw new Error('Controller URL is required for governed local configuration');
+  const deploymentType = await (deps.getControllerDeploymentType || getControllerDeploymentType)(controllerUrl);
+  if (!LOCAL_DEPLOYMENTS.has(String(deploymentType || '').toLowerCase())) return null;
+  const templatePath = path.join((deps.getBuilderPath || getBuilderPath)(appName), 'env.template');
+  const templateContent = await readFile(templatePath, 'utf8');
+  const catalog = (deps.getInfraParameterCatalog || getInfraParameterCatalog)();
+  return {
+    controllerUrl,
+    credentials: credentialPair(env),
+    rows: uniqueRows(mapEnvToCatalogKeys(envContent, templateContent), catalog)
+  };
+}
+
+/**
+ * Initialize unresolved local parameter rows needed by a client-credentials snapshot.
+ * @param {string} appName Application key
+ * @param {string} runEnvPath Resolved app-only run env
+ * @param {Object} [deps] Test dependencies
+ * @returns {Promise<number>} Number of rows initialized
+ */
+async function hydrateMissingLocalParameters(appName, runEnvPath, deps = {}) {
+  const context = await resolveSyncContext(appName, runEnvPath, deps);
+  if (!context || context.rows.length === 0) return 0;
+  const response = await (deps.getToken || getToken)(
+    context.credentials.clientId,
+    context.credentials.clientSecret,
+    context.controllerUrl
+  );
+  const client = deps.client || new ApiClient(context.controllerUrl, {
+    type: 'client-token', token: tokenFrom(response)
+  });
+  let initialized = 0;
+  for (const row of context.rows) {
+    if (!(await isMissing(client, row.catalogKey))) continue;
+    await writeMissing(client, row);
+    initialized += 1;
+  }
+  return initialized;
+}
+
+module.exports = {
+  credentialPair,
+  hydrateMissingLocalParameters,
+  tokenFrom,
+  uniqueRows
+};

package/lib/app/run.js

@@ -258,10 +258,12 @@ function applyTraefikFlagToRunOptions(runOptions, userCfg) {
 
 /**
  * @param {string} envKey
- * @throws {Error} If env is not dev, tst, or pro
+ * @param {string} appName
+ * @throws {Error} If env is not a supported workload environment or a miso-only platform app
  */
-function assertValidRunEnvKey(envKey) {
-  if (envKey !== 'dev' && envKey !== 'tst' && envKey !== 'pro') {
+function assertValidRunEnvKey(envKey, appName) {
+  const misoOnlyPlatformApp = appName === 'builder-api' || appName === 'integration-server';
+  if (envKey !== 'dev' && envKey !== 'tst' && envKey !== 'pro' && !(envKey === 'miso' && misoOnlyPlatformApp)) {
     throw new Error('--env must be dev, tst, or pro');
   }
 }
@@ -345,7 +347,7 @@ function emitRunManifestMetadataIfRequested(appName, options) {
  */
 async function prepareAppRun(appName, options, debug) {
   const envKey = (options.env || 'dev').toLowerCase();
-  assertValidRunEnvKey(envKey);
+  assertValidRunEnvKey(envKey, appName);
   const shouldContinue = await validateAppForRun(appName, debug);
   if (!shouldContinue) {
     return null;

package/lib/build/docker-build-args.js

@@ -52,10 +52,13 @@ function applyMisoControllerUiBuildArgs(buildArgs, envMap) {
  *
  * @param {string} appName
  * @param {string} [contextPath] Docker build context (repo root for miso-controller)
+ * @param {Object} [options] - `runEnvKey`: environment key for manifest {NAME} resolution
+ *   (defaults to the current CLI environment inside generateEnvContent)
  * @returns {Promise<Object.<string, string>>}
  */
-async function resolveDockerBuildArgsForApp(appName, contextPath) {
-  const envMap = await secretsEnvWrite.resolveAndGetEnvMap(appName, { environment: 'docker' });
+async function resolveDockerBuildArgsForApp(appName, contextPath, options = {}) {
+  const runEnvKey = options && options.runEnvKey ? String(options.runEnvKey) : undefined;
+  const envMap = await secretsEnvWrite.resolveAndGetEnvMap(appName, { environment: 'docker', runEnvKey });
   const { getBashPrefixedProcessEnvOverlay } = require('../utils/bash-secret-env');
   const bashOverlay = await getBashPrefixedProcessEnvOverlay(null, appName);
   const buildArgs = {};

package/lib/build/index.js

@@ -191,12 +191,13 @@ async function generateDockerfile(appNameOrPath, language, config, buildConfig =
  * @param {Object} options - Build options
  */
 
-async function postBuildTasks(appName, buildConfig) {
+async function postBuildTasks(appName, buildConfig, options = {}) {
   try {
     // Validate that env.template + secrets resolve cleanly, but never write <appPath>/.env or
     // envOutputPath. Build args still flow through resolveAndGetEnvMap (in-memory). Run
     // `aifabrix resolve <app>` to materialize an on-disk .env.
-    await secrets.generateEnvFile(appName, buildConfig.secrets, 'docker', false, { noWrite: true });
+    const runEnvKey = options && options.env ? String(options.env) : undefined;
+    await secrets.generateEnvFile(appName, buildConfig.secrets, 'docker', false, { noWrite: true, runEnvKey });
     logger.log(formatSuccessLine('Env resolution validated (in-memory only; run "aifabrix resolve ' + appName + '" for on-disk .env)'));
   } catch (error) {
     logger.log(formatWarningLine(`Could not resolve env: ${error.message}`));

package/lib/build/standard-docker-build.js

@@ -79,7 +79,7 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
     buildHelpers
   );
   await ensureRunSecretsForApp(appName);
-  const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath);
+  const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath, { runEnvKey: options.env });
   const { primary, aliases, tags } = options.tagPlan;
   // `build.target` selects a stage of a multi-stage Dockerfile, so one source tree can
   // produce more than one image. Absent, Docker builds the last stage as before.
@@ -92,7 +92,7 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
     primary,
     { ...options, buildArgs, tagAliases: aliases, target }
   );
-  await postBuildTasks(appName, buildConfig);
+  await postBuildTasks(appName, buildConfig, options);
   logger.log(formatSuccessParagraph('Build completed successfully!'));
   return tags.map((tag) => `${effectiveImageName}:${tag}`).join(', ');
 }
@@ -104,6 +104,10 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
  * @returns {Promise<string>} Built image ref e.g. name:tag
  */
 async function runStandardDockerBuild(appName, options) {
+  // Before the tag plan, the promote shortcut and any Docker call: every build path reaches
+  // here, and a build into tst or pro must not get as far as producing an artifact.
+  const { assertBuildEnvironmentForOptions } = require('../core/environment-mode-policy');
+  await assertBuildEnvironmentForOptions(options);
   const { resolveBuildTagPlan, readAppVersion } = require('../utils/image-tags');
   const { buildConfig, config: appConfig } = await buildHelpers.loadAndValidateConfig(appName);
   // Resolve and validate every tag before any Docker build, tag, login or promote.

package/lib/channels/channel-artifact-generator.js

@@ -92,7 +92,7 @@ function renderTemplateFile(templatePath, context) {
  * @param {boolean} dryRun
  * @returns {{ installPath: string, content: string }|null}
  */
-function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dryRun) {
+function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dryRun, durableDir) {
   const installTemplate = path.join(templatesDir, 'install.template.md.hbs');
   if (!fs.existsSync(installTemplate)) {
     return null;
@@ -100,11 +100,19 @@ function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dry
   const content = renderTemplateFile(installTemplate, runtimeValues);
   assertNoSecretsInArtifact(content);
   const installPath = path.join(outputDir, 'INSTALL.md');
+  // `outputDir` is under gitignored dist/, so a copy there alone is lost on any clean and the
+  // API that serves this document 404s afterwards. Write the durable copy too when the caller
+  // knows where the channel's committed files live.
+  const durablePath = durableDir ? path.join(durableDir, 'INSTALL.md') : '';
   if (!dryRun) {
     fs.mkdirSync(outputDir, { recursive: true });
     fs.writeFileSync(installPath, content, 'utf8');
+    if (durablePath) {
+      fs.mkdirSync(durableDir, { recursive: true });
+      fs.writeFileSync(durablePath, content, 'utf8');
+    }
   }
-  return { installPath, content };
+  return { installPath, content, durablePath: durablePath || undefined };
 }
 
 /**
@@ -130,6 +138,7 @@ function generateCopilotChannelArtifact(params, templatesDir, outputPath) {
  * @param {string} params.channelTarget
  * @param {Object} params.runtimeValues
  * @param {boolean} [params.dryRun]
+ * @param {string} [params.durableDir] - Committed channel directory for the persisted INSTALL.md
  * @returns {{ outputPath: string, artifactHash: string, content: string, installPath?: string }}
  */
 function generateChannelArtifact(params) {
@@ -158,7 +167,8 @@ function generateChannelArtifact(params) {
     templatesDir,
     runtimeValues,
     outputDir,
-    params.dryRun === true
+    params.dryRun === true,
+    params.durableDir
   );
 
   const installReady = runtimeValues?.installReady === true;

package/lib/cli/infra-guided-footers.js

@@ -46,11 +46,12 @@ async function resolvePlatformControllerUrlForDisplay() {
   return resolvePlatformControllerUrl();
 }
 
-async function logPlatformReadyFooter() {
-  const [controllerUrl, dataplaneUrl, keycloakUrl] = await Promise.all([
+async function logPlatformReadyFooter(options = {}) {
+  const [controllerUrl, dataplaneUrl, keycloakUrl, integrationServerUrl] = await Promise.all([
     resolvePlatformControllerUrlForDisplay(),
     computeAppBaseUrl('dataplane'),
-    computeAppBaseUrl('keycloak')
+    computeAppBaseUrl('keycloak'),
+    options.integrationServer === true ? computeAppBaseUrl('integration-server') : null
   ]);
   const cfg = await config.getConfig();
   const env = cfg && cfg.environment ? cfg.environment : 'dev';
@@ -60,7 +61,7 @@ async function logPlatformReadyFooter() {
   logSection('Miso Controller', controllerUrl);
   logSection('Dataplane (DEV)', dataplaneUrl);
   logSection('Keycloak', keycloakUrl);
-  logSection('API Documentation', `${dataplaneUrl}/api/docs`);
+  if (integrationServerUrl) logSection('Integration Server', `${integrationServerUrl}/download`);
   logSection('Knowledge Base', 'https://docs.aifabrix.ai');
   logSection('Getting Started', 'https://docs.aifabrix.ai/get-started');
   logFooterEnd();
@@ -91,20 +92,21 @@ async function logDataplaneReadyFooter() {
 /**
  * @param {'platform'|'dataplane'} [scope]
  */
-function logPlatformSetupDurationHint(scope = 'platform') {
+function logPlatformSetupDurationHint(scope = 'platform', options = {}) {
+  const optionalApp = options.integrationServer === true ? ', Builder API, and Integration Server' : ', and Builder API';
   const line =
     scope === 'dataplane'
       ? 'Installation may take a few minutes. Authenticating and starting Dataplane — please wait.'
-      : 'Installation may take a few minutes. Keycloak, Miso Controller, Dataplane, and Builder API are starting — please wait.';
+      : `Installation may take a few minutes. Keycloak, Miso Controller, Dataplane${optionalApp} are starting — please wait.`;
   logger.log(chalk.yellow(`⚠ ${line}`));
 }
 
-function logGuidedPlatformSetupHeader() {
+function logGuidedPlatformSetupHeader(options = {}) {
   logger.log('');
   logger.log(title('AI Fabrix Platform Setup'));
   logger.log(SEPARATOR);
   logger.log('');
-  logPlatformSetupDurationHint('platform');
+  logPlatformSetupDurationHint('platform', options);
   logger.log('');
 }
 

package/lib/cli/infra-guided.js

@@ -14,6 +14,10 @@ const { execWithDockerEnv } = require('../utils/docker-exec');
 const { getLogLevel, passesLevelFilter } = require('../commands/app-logs');
 const { handleLogin } = require('../commands/login');
 const { handleUpBuilderApi } = require('../commands/up-builder-api');
+const {
+  handleUpIntegrationServer,
+  isIntegrationServerSelected
+} = require('../commands/up-integration-server');
 const {
   resolveGuidedAuthControllerUrl,
   runGuidedAuthStep,
@@ -295,8 +299,25 @@ async function runGuidedDataplaneInstallPhase(options, handleUpDataplane, handle
   await refreshDataplaneVersionAfterPlatformInstall();
 }
 
+async function runGuidedIntegrationServerPhase(options, selected) {
+  if (!selected) return;
+  const spin = startSpinner('Starting Integration Server...');
+  await withMutedLogger(() => handleUpIntegrationServer({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(spin, 'Integration Server ready');
+}
+
+async function runGuidedKeycloakRealmPhase(options) {
+  if (!options || options.requireKeycloakRealm !== true) return;
+  const { waitForKeycloakRealmReady } = require('../utils/keycloak-realm-ready');
+  const spin = startSpinner('Waiting for Keycloak realm (aifabrix)...');
+  await waitForKeycloakRealmReady({ timeoutSeconds: 180 });
+  stopSpinnerSuccess(spin, 'Keycloak realm ready');
+  logger.log('');
+}
+
 async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, handleLogin, forceCleanSummary = null) {
-  logGuidedPlatformSetupHeader();
+  const integrationServerSelected = await isIntegrationServerSelected();
+  logGuidedPlatformSetupHeader({ integrationServer: integrationServerSelected });
   if (forceCleanSummary && forceCleanSummary.forceSummary) {
     logUpPlatformForceCleanSummary(forceCleanSummary.forceSummary, forceCleanSummary.cleanedApps);
   }
@@ -308,21 +329,20 @@ async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, han
 
   await withMutedLogger(() => prepareUrlsLocalRegistryForUpPlatform());
   await runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso);
-  if (options && options.requireKeycloakRealm === true) {
-    const { waitForKeycloakRealmReady } = require('../utils/keycloak-realm-ready');
-    const realmSpin = startSpinner('Waiting for Keycloak realm (aifabrix)...');
-    await waitForKeycloakRealmReady({ timeoutSeconds: 180 });
-    stopSpinnerSuccess(realmSpin, 'Keycloak realm ready');
-    logger.log('');
-  }
+  await runGuidedKeycloakRealmPhase(options);
   await runGuidedAuthStep(handleLogin, authOpts, { startSpinner, stopSpinnerSuccess });
   const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
   await runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLogin, controllerUrl);
   const baSpin = startSpinner('Starting Builder API...');
   await withMutedLogger(() => handleUpBuilderApi({ ...options, platformInstall: true }));
   stopSpinnerSuccess(baSpin, 'Builder API ready');
-  await validateAppErrorLogs(['miso-controller', 'dataplane', 'builder-api']);
-  await logPlatformReadyFooter();
+  await runGuidedIntegrationServerPhase(options, integrationServerSelected);
+  const appNames = [
+    'miso-controller', 'dataplane', 'builder-api',
+    ...(integrationServerSelected ? ['integration-server'] : [])
+  ];
+  await validateAppErrorLogs(appNames);
+  await logPlatformReadyFooter({ integrationServer: integrationServerSelected });
 }
 
 async function runGuidedDownInfra(appName, options, infraMod, appLib) {

package/lib/cli/setup-app.js

@@ -243,6 +243,10 @@ function registerBuildCommand(program) {
       'Image tag or comma-separated tags (default: latest); {version} expands to app.version, e.g. "latest,{version}"'
     )
     .option('-r, --registry <registry>', 'Registry host for the image name (overrides dev set-registry and application.yaml)')
+    .option(
+      '-e, --env <env>',
+      'Environment key used to resolve manifest {NAME} values (dev|tst|pro); defaults to the current CLI environment'
+    )
     .option(
       '--base',
       'Build/run the manifest base image (no -devN suffix). Default local build uses a developer-scoped repository when developer-id > 0.'
@@ -255,6 +259,7 @@ function registerBuildCommand(program) {
 Examples:
   $ aifabrix build myapp
   $ aifabrix build myapp --tag v1.0.0            # also tags latest
+  $ aifabrix build myapp --env dev               # resolve manifest {NAME} values for dev
   $ aifabrix build myapp --base --from-dev --tag 'latest,{version}'
   $ aifabrix build myapp --registry myregistry.azurecr.io`)
     .action(async(appName, options) => {