@aifabrix/builder 2.59.0 → 2.61.2

package/lib/api/configuration.api.js

@@ -0,0 +1,131 @@
+/**
+ * Parameter-backed installation configuration API.
+ *
+ * @fileoverview Read safe configuration metadata from Miso Controller
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const PAGE_SIZE = 100;
+
+/**
+ * @param {string} envKey - Environment key
+ * @returns {string} Configuration collection endpoint
+ */
+function configurationEndpoint(envKey) {
+  return `/api/v1/environments/${encodeURIComponent(envKey)}/configuration`;
+}
+
+/**
+ * @param {Object} meta - Pagination metadata
+ * @param {number} requestedPage - Requested one-based page
+ * @param {boolean} hasRows - Whether the page contains rows
+ * @returns {number} Validated total page count
+ */
+function validatePageMeta(meta, requestedPage, hasRows) {
+  const currentPage = Number(meta && meta.currentPage);
+  const totalPages = Number(meta && meta.totalPages);
+  if (!Number.isInteger(currentPage) || currentPage !== requestedPage) {
+    throw new Error('Configuration list response has invalid pagination metadata');
+  }
+  if (!Number.isInteger(totalPages) || totalPages < 0 || (hasRows && totalPages === 0)) {
+    throw new Error('Configuration list response has invalid pagination metadata');
+  }
+  return totalPages;
+}
+
+/**
+ * @param {Object} response - API response
+ * @param {number} requestedPage - Requested one-based page
+ * @returns {{ rows: Object[], totalPages: number }} Validated page
+ */
+function readConfigurationPage(response, requestedPage) {
+  if (response && response.success === false) {
+    throw new Error(response.formattedError || response.error || 'Configuration list request failed');
+  }
+  const body = response && response.data !== undefined ? response.data : response;
+  if (!body || !Array.isArray(body.data) || !body.meta) {
+    throw new Error('Configuration list response is not a paginated result');
+  }
+  const totalPages = validatePageMeta(body.meta, requestedPage, body.data.length > 0);
+  return { rows: body.data, totalPages };
+}
+
+/**
+ * List configuration declarations, optionally for one exact owner.
+ *
+ * GET /api/v1/environments/{envKey}/configuration
+ * @requiresPermission {Controller} controller:monitor or admin:read
+ * @async
+ * @function listEnvironmentConfiguration
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} [application] - Exact owning application key
+ * @param {Object} [options] - Optional safe search
+ * @param {string} [options.search] - Partial key/name search
+ * @returns {Promise<Object[]>} Safe configuration metadata rows
+ */
+async function listEnvironmentConfiguration(controllerUrl, authConfig, envKey, application, options = {}) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  const environment = typeof envKey === 'string' ? envKey.trim() : '';
+  const owner = typeof application === 'string' ? application.trim() : '';
+  if (!environment) {
+    throw new Error('envKey is required and must be a string');
+  }
+  const client = new ApiClient(controllerUrl, authConfig);
+  const common = {
+    pageSize: PAGE_SIZE,
+    sort: owner ? 'key' : 'application'
+  };
+  if (owner) common.application = owner;
+  if (options.search) common.search = String(options.search).trim();
+  const rows = [];
+  for (let page = 1;; page += 1) {
+    const response = await client.get(configurationEndpoint(environment), {
+      params: { ...common, page }
+    });
+    const result = readConfigurationPage(response, page);
+    rows.push(...result.rows);
+    if (page >= result.totalPages) return rows;
+  }
+}
+
+/**
+ * Update one authoritatively non-sensitive configuration declaration.
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} application - Exact application owner
+ * @param {string} key - Configuration declaration key
+ * @param {Object} update - Value and concurrency revision
+ * @param {string} update.value - Non-sensitive value
+ * @param {string} update.revision - Opaque revision from the configuration list
+ * @returns {Promise<Object>} Safe updated metadata
+ */
+async function putEnvironmentConfiguration(
+  controllerUrl, authConfig, envKey, application, key, update
+) {
+  const value = update && update.value;
+  const revision = update && update.revision;
+  const required = { controllerUrl, envKey, application, key, revision };
+  for (const [name, input] of Object.entries(required)) {
+    if (!input || typeof input !== 'string') throw new Error(`${name} is required`);
+  }
+  if (typeof value !== 'string') throw new Error('value must be a string');
+  const client = new ApiClient(controllerUrl, authConfig);
+  const endpoint = `${configurationEndpoint(envKey)}/${encodeURIComponent(application)}/` +
+    encodeURIComponent(key);
+  return await client.put(endpoint, { body: { value }, headers: { 'If-Match': revision } });
+}
+
+module.exports = {
+  listEnvironmentConfiguration,
+  putEnvironmentConfiguration
+};

package/lib/api/role-assistant-test-job.api.js

@@ -0,0 +1,60 @@
+/**
+ * Dataplane asynchronous Role Assistant test job API.
+ *
+ * @fileoverview Enqueue and poll published Role Assistant cases
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { throwIfApiFailed } = require('./api-response-errors');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+function jobPath(systemIdOrKey, suffix = '') {
+  const key = encodeURIComponent(String(systemIdOrKey || '').trim());
+  return `/api/v1/external/systems/${key}/role-assistant-tests/jobs${suffix}`;
+}
+
+function unwrapJob(res) {
+  const value = unwrapApiData(res);
+  if (value && typeof value === 'object' && !Array.isArray(value) && value.data) {
+    return value.data;
+  }
+  return value;
+}
+
+async function enqueueRoleAssistantTestJob(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  body
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const path = jobPath(systemIdOrKey);
+  const res = await client.post(path, { body, timeoutMs: 60000 });
+  throwIfApiFailed(res, {
+    endpointUrl: `${String(dataplaneUrl || '').replace(/\/$/, '')}${path}`
+  });
+  return unwrapJob(res);
+}
+
+async function getRoleAssistantTestJob(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  jobId
+) {
+  const suffix = `/${encodeURIComponent(String(jobId || '').trim())}`;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const path = jobPath(systemIdOrKey, suffix);
+  const res = await client.get(path, { timeoutMs: 60000 });
+  throwIfApiFailed(res, {
+    endpointUrl: `${String(dataplaneUrl || '').replace(/\/$/, '')}${path}`
+  });
+  return unwrapJob(res);
+}
+
+module.exports = {
+  enqueueRoleAssistantTestJob,
+  getRoleAssistantTestJob
+};

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/api/work-search.api.js

@@ -121,16 +121,23 @@ async function getWorkRoles(dataplaneUrl, authConfig) {
 
 /**
  * GET-equivalent work.skills for one roleRef.
- * Requests detail=full so search.resourceTypes (executable grammar) is present.
- * Compact summary omits that slice and cannot evaluate named viewpoint ops.
+ * Defaults to detail=full so search.resourceTypes (executable grammar) is present.
+ * A caller may request progressive resource/operation detail for skills-only checks.
  * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  */
-async function getWorkSkills(dataplaneUrl, authConfig, roleRef) {
-  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.skills, {
+async function getWorkSkills(dataplaneUrl, authConfig, roleRef, options = {}) {
+  const args = {
     roleRef: String(roleRef || '').trim(),
-    detail: 'full'
-  });
+    detail: String(options.detail || 'full').trim()
+  };
+  if (typeof options.resourceType === 'string' && options.resourceType.trim()) {
+    args.resourceType = options.resourceType.trim();
+  }
+  if (typeof options.operation === 'string' && options.operation.trim()) {
+    args.operation = options.operation.trim();
+  }
+  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.skills, args);
 }
 
 /**

package/lib/app/deploy.js

@@ -268,7 +268,14 @@ async function executeStandardDeployment(appName, options) {
   const controllerUrl = config.controllerUrl || 'unknown';
   const appExists = await checkApplicationExists(appName, controllerUrl, config.envKey, config.auth);
 
-  const { manifest, manifestPath } = await generateAndValidateManifest(appName, options);
+  // A controller deployment ships tokens plus the platforms/environments sections, so the
+  // Controller resolves them per installation and can promote dev -> tst without regenerating.
+  // Local runs and an explicit --resource-group resolve here instead.
+  const resolveHere = Boolean(options.local || options.resourceGroup);
+  const { manifest, manifestPath } = await generateAndValidateManifest(appName, {
+    ...options,
+    ...(resolveHere ? { target: { environment: config.envKey, resourceGroup: options.resourceGroup } } : {})
+  });
   applyManifestOverrides(manifest, options);
   validateImageIsPullable(manifest.image, appName);
   displayDeploymentInfo(manifest, manifestPath);

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-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/show-display.js

@@ -234,6 +234,7 @@ function logExternalSystemMain(ext) {
   logger.log(`  Version:       ${ext.version ?? '—'}`);
   logger.log(`  Credential:    ${formatCredentialShowLine(ext)}`);
   logger.log(`  Status:        ${formatDataplaneStatusDisplay(ext.status)}`);
+  logger.log(`  System link:   ${ext.systemUrl ?? '—'}`);
   logger.log(`  API docs:      ${ext.openApiDocsPageUrl ?? ext.apiDocumentUrl ?? '—'}`);
   logger.log(`  MCP server:    ${ext.mcpServerUrl ?? '—'}`);
   logger.log(`  OpenAPI spec:  ${ext.apiDocumentUrl ?? '—'}`);

package/lib/app/show-online.js

@@ -89,6 +89,7 @@ function buildOnlineSummaryFromDataplane(appKey, controllerUrl, dataplaneUrl, ex
 
 async function finishOnlineShow(summary, appKey, json, permissionsOnly, verifyCert, authBundle) {
   await enrichExternalShowSummary(summary, appKey, verifyCert, authBundle);
+  attachSystemUrl(summary);
   attachRunDefaultsFromUserConfig(summary, appKey, await getConfig());
   await attachDeclarativeUrlsToShowApplication(summary, appKey);
   if (json) {
@@ -100,6 +101,20 @@ async function finishOnlineShow(summary, appKey, json, permissionsOnly, verifyCe
   displayShow(summary, { permissionsOnly: !!permissionsOnly });
 }
 
+/**
+ * Expose the Dataplane system browser route for humans and agents.
+ * Preserve the deployment base path (for example /data).
+ * @param {Object} summary - Online application summary
+ */
+function attachSystemUrl(summary) {
+  const ext = summary.externalSystem;
+  if (!summary.isExternal || !ext || ext.error || !ext.dataplaneUrl) return;
+  const baseUrl = ext.dataplaneUrl.replace(/\/+$/, '');
+  const systemKey = ext.systemKey || summary.appKey;
+  const section = /^(ra-|ek-)/.test(systemKey) ? 'enterprise-knowledge' : 'connected-systems';
+  ext.systemUrl = `${baseUrl}/${section}/${encodeURIComponent(systemKey)}`;
+}
+
 async function runOnlineFromDataplane(appKey, json, permissionsOnly, verifyCert, authConfig, authResult) {
   const environment = await resolveEnvironment();
   const dataplaneUrl = await resolveDataplaneUrl(authResult.actualControllerUrl, environment, authConfig);

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,17 +79,20 @@ 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.
+  const target = buildConfig && buildConfig.target;
   await dockerBuild.executeDockerBuildWithTag(
     effectiveImageName,
     imageName,
     dockerfilePath,
     contextPath,
     primary,
-    { ...options, buildArgs, tagAliases: aliases }
+    { ...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(', ');
 }

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) => {
@@ -362,7 +367,7 @@ function setupDockerfileGenerateCommand(program) {
 }
 
 function setupDeployCommand(program) {
-  program.command('deploy <appKey|systemKey>')
+  addDeployTargetOptions(program.command('deploy <appKey|systemKey>'))
     .description('Deploy builder app or external system via Miso Controller (Azure or --local)')
     .addHelpText('after', DEPLOY_HELP_AFTER)
     .option('--local', 'Send manifest to controller then run app locally (app: same as aifabrix run <app>; external: restart dataplane)')
@@ -410,6 +415,19 @@ function setupDeployCommand(program) {
     });
 }
 
+/**
+ * Deployment-target options. A controller deployment normally ships {NAME} tokens plus the
+ * platforms/environments sections; these flags force local resolution instead.
+ * @param {Command} command - Commander command
+ * @returns {Command} The command
+ */
+function addDeployTargetOptions(command) {
+  return command.option(
+    '-g, --resource-group <name>',
+    'Target Azure resource group; resolves platforms values in the generated manifest instead of shipping tokens'
+  );
+}
+
 function setupPushDeployDockerfileCommands(program) {
   program.command('push <appKey>')
     .description('Push builder appKey image to Azure Container Registry')