@aifabrix/builder 2.59.0 → 2.61.2

package/lib/schema/infrastructure-schema.json

@@ -7,12 +7,12 @@
     "key": "infrastructure-schema",
     "name": "Installation Infrastructure Manifest Schema",
     "description": "JSON schema for infrastructure/<resource-group>/environment-infra.json",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "type": "schema",
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-09-17T00:00:00Z",
+    "updatedAt": "2026-09-24T00:00:00Z",
     "compatibility": {
       "minVersion": "2.0.0",
       "maxVersion": "2.0.0",
@@ -26,6 +26,14 @@
     ],
     "dependencies": [],
     "changelog": [
+      {
+        "version": "2.1.0",
+        "date": "2026-09-24T00:00:00Z",
+        "breaking": false,
+        "changes": [
+          "Removed moriCallbackApiKey and entraCallbackStateSecret: the shipped Marketplace template no longer declares them. The installation receives its Mori key at licence registration, and Entra consent state is issued server-side (Mori 227.5)."
+        ]
+      },
       {
         "version": "2.0.0",
         "date": "2026-09-16T00:00:00Z",
@@ -501,8 +509,6 @@
         "acrResourceId",
         "deployRoleAssignments",
         "moriBaseUrl",
-        "moriCallbackApiKey",
-        "entraCallbackStateSecret",
         "entraIdClientId",
         "entraIdClientSecret",
         "entraIdTenantId",
@@ -1058,37 +1064,6 @@
             }
           }
         },
-        "moriCallbackApiKey": {
-          "$ref": "#/definitions/envReference"
-        },
-        "entraCallbackStateSecret": {
-          "type": "object",
-          "required": [
-            "value",
-            "source",
-            "description"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "value": {
-              "type": "null"
-            },
-            "source": {
-              "type": "string",
-              "minLength": 1
-            },
-            "description": {
-              "type": "string",
-              "minLength": 1
-            },
-            "required": {
-              "type": "boolean"
-            },
-            "requiredAt": {
-              "const": "tenantActivation"
-            }
-          }
-        },
         "entraIdClientId": {
           "type": "object",
           "required": [

package/lib/utils/compose-generate-docker-compose.js

@@ -11,6 +11,7 @@
 const fsSync = require('fs');
 const path = require('path');
 const buildCopy = require('./build-copy');
+const { prepareLocalDataMount } = require('./prepare-local-data-mount');
 const paths = require('./paths');
 const { isSystemBuilderAppName } = require('./paths-system-builder-keys');
 const {
@@ -187,14 +188,14 @@ function resolveStorageMountSourceRoot(appName, buildContext) {
 }
 
 /**
- * Host `mount/` directory bind-mounted to `/mnt/data` when storage is required.
+ * Host `mount/data/<appName>/` directory bind-mounted to `/mnt/data` when storage is required.
  *
  * @param {object} ctx - Compose template context (`devMountPath`, `appName`, `appConfig`, `serviceConfig`)
  * @returns {string|null}
  */
 function resolveLocalDataMountPathForCompose(ctx) {
   if (ctx.devMountPath && typeof ctx.devMountPath === 'string') {
-    return path.join(ctx.devMountPath, 'mount').replace(/\\/g, '/');
+    return path.join(ctx.devMountPath, 'mount', 'data', ctx.appName).replace(/\\/g, '/');
   }
   const requiresStorage =
     ctx.serviceConfig?.requiresStorage ||
@@ -212,7 +213,7 @@ function resolveLocalDataMountPathForCompose(ctx) {
     if (!sourceRoot) {
       return null;
     }
-    return path.join(sourceRoot, 'mount').replace(/\\/g, '/');
+    return path.join(sourceRoot, 'mount', 'data', ctx.appName).replace(/\\/g, '/');
   } catch {
     return null;
   }
@@ -229,12 +230,8 @@ function buildComposeTemplateContext(ctx) {
     ctx.appConfig?.requires?.storage ||
     ctx.appConfig?.services?.storage ||
     false;
-  if (localDataMountPath && requiresStorage && !fsSync.existsSync(localDataMountPath)) {
-    try {
-      fsSync.mkdirSync(localDataMountPath, { recursive: true });
-    } catch {
-      // Non-fatal: tests may use non-writable devMountPath; host must create mount/ before run.
-    }
+  if (localDataMountPath && requiresStorage) {
+    prepareLocalDataMount(localDataMountPath, ctx.envFileAbsolutePath);
   }
   return {
     ...ctx.serviceConfig,
@@ -249,6 +246,16 @@ function buildComposeTemplateContext(ctx) {
     networkName: ctx.networkName,
     containerName: ctx.containerName,
     misoEnvironment: resolveMisoEnvironment(ctx.options),
+    // Containers are run as the invoking host user so bind-mounted files stay writable.
+    // An app that administers its own operating system — creating accounts, managing
+    // sshd — cannot work that way and declares `runAsRoot: true` to opt out.
+    runAsRoot: ctx.appConfig?.runAsRoot === true,
+    // Extra protocol ports use the main port offset formula to avoid developer collisions.
+    additionalPorts: (ctx.appConfig?.additionalPorts ?? []).map((entry) => ({
+      name: entry.name,
+      containerPort: entry.containerPort,
+      hostPort: ctx.idNum === 0 ? entry.hostPort : entry.hostPort + ctx.idNum * 100
+    })),
     devMountPath: ctx.devMountPath,
     localDataMountPath,
     reloadStartCommand: ctx.reloadStartCommand,

package/lib/utils/datasource-binary-evidence.js

@@ -0,0 +1,92 @@
+/** @fileoverview Safe binary metadata and keyed document persistence evidence. */
+'use strict';
+
+const { keyedGetEvidence, hasExecutedKeyedGet } = require('./datasource-test-run-capability-scope');
+const BINARY_FIELDS = new Set(['contentType', 'size', 'filename', 'sha256']);
+
+/** @param {*} value @returns {Object} */
+function binarySummary(value) {
+  if (!value || typeof value !== 'object') return {};
+  return Object.fromEntries(Object.entries(value).filter(([key, item]) =>
+    BINARY_FIELDS.has(key) && ['string', 'number'].includes(typeof item)));
+}
+
+/**
+ * Limit binary containers to metadata before printing or saving a report.
+ * Ordinary JSON record fields remain intact.
+ * @param {*} value
+ * @param {WeakSet} seen
+ * @returns {*}
+ */
+function sanitizeBinaryEvidence(value, seen = new WeakSet()) {
+  if (!value || typeof value !== 'object') return value;
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value)) return '[binary omitted]';
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const items = value.map(item => sanitizeBinaryEvidence(item, seen));
+    seen.delete(value);
+    return items;
+  }
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (['getBinary', 'listBinary', '_binary'].includes(key)) out[key] = binarySummary(item);
+    else if (value.keyedGet === true && key === 'document') {
+      out[key] = { ...binarySummary(item) };
+      if (typeof item?.key === 'string') out[key].key = item.key;
+      if (typeof item?.persisted === 'boolean') out[key].persisted = item.persisted;
+    } else if (value.keyedGet === true && ['data', 'bytes', 'body', 'content', 'base64'].includes(key)) continue;
+    else out[key] = sanitizeBinaryEvidence(item, seen);
+  }
+  seen.delete(value);
+  return out;
+}
+
+/** @param {Object} value @param {string[]} lines */
+function appendBinaryAndPersistence(value, lines) {
+  if (!value || typeof value !== 'object') return;
+  if (value.getBinary) lines.push(`  getBinary: ${JSON.stringify(binarySummary(value.getBinary))}`);
+  if (value.scope?.expectedSource === 'get') {
+    const observed = value.observed || {};
+    lines.push(`  Document persistence (expectedSource: get): documents=${Number(observed.documents) || 0}, chunks=${Number(observed.chunks) || 0}`);
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (key !== 'getBinary') appendBinaryAndPersistence(child, lines);
+  }
+}
+
+/** @param {Object} envelope @returns {string[]} */
+function binaryEvidenceLines(envelope) {
+  const lines = [];
+  for (const job of keyedGetEvidence(envelope)) {
+    const status = job.skipped === true ? 'skipped' : job.ok === true ? 'executed' : 'failed';
+    lines.push(`  Keyed get: ${status} (${job.datasourceKey || envelope.datasourceKey || 'unknown'})`);
+    if (job.document) lines.push(`  Document: ${JSON.stringify(binarySummary(job.document))}`);
+  }
+  appendBinaryAndPersistence(envelope?.integration?.stepResults, lines);
+  return lines;
+}
+
+/** @param {Object} envelope @param {string} key @returns {boolean} */
+function hasKeyedDocumentPersistence(envelope, key) {
+  if (!hasExecutedKeyedGet(envelope, key)) return false;
+  const steps = envelope?.integration?.stepResults || [];
+  return steps.some(step => {
+    if (step.name !== 'document_persistence' || step.success === false || step.status === 'failed') return false;
+    const row = step.evidence?.datasources?.[key];
+    const model = row?.model;
+    return model?.scope?.expectedSource === 'get' && model.observed?.documents > 0 &&
+      model.observed?.chunks > 0 && (!Array.isArray(row.failures) || row.failures.length === 0);
+  });
+}
+
+/** @param {Object} result @param {string[]} keys @returns {boolean} */
+function hasAllKeyedDocumentPersistence(result, keys) {
+  return keys.length > 0 && keys.every(key => {
+    const row = result?.results?.find(item => item.key === key);
+    return row?.success === true && hasKeyedDocumentPersistence(row.datasourceTestRun, key);
+  });
+}
+
+module.exports = { binarySummary, sanitizeBinaryEvidence, binaryEvidenceLines, hasKeyedDocumentPersistence,
+  hasAllKeyedDocumentPersistence };

package/lib/utils/datasource-test-run-capability-scope.js

@@ -4,6 +4,43 @@
  * @version 2.0.0
  */
 
+/**
+ * Keyed document retrieval has no list operation, so the `get` runs once against a business
+ * key instead of over a sync page. The dataplane records that run as step evidence
+ * (`sync_step_keyed_get.py`), which is why execution is read from evidence rather than from
+ * a row count. `IntegrationStepResult.evidence` is an open object by contract.
+ * @param {Object|null|undefined} envelope - DatasourceTestRun-like
+ * @returns {Array<Object>} Keyed-get evidence entries, newest first as reported
+ */
+function keyedGetEvidence(envelope) {
+  const integration = envelope && typeof envelope === 'object' ? envelope.integration : null;
+  const steps = integration && Array.isArray(integration.stepResults) ? integration.stepResults : [];
+  return steps
+    .map(step => (step && typeof step.evidence === 'object' ? step.evidence : null))
+    .flatMap(evidence => evidence && Array.isArray(evidence.jobs) ? evidence.jobs : [evidence])
+    .filter(evidence => evidence && evidence.keyedGet === true);
+}
+
+/**
+ * A keyed `get` counts as executed only when it actually returned a document. A skipped run
+ * (no primary key value) or a failed one is not execution, and reporting it as such would
+ * turn `--strict-capability-scope` into a rubber stamp.
+ * @param {Object|null|undefined} envelope - DatasourceTestRun-like
+ * @param {string|undefined|null} datasourceKey - Restrict to one datasource when given
+ * @returns {boolean} True when a keyed get ran successfully
+ */
+function hasExecutedKeyedGet(envelope, datasourceKey) {
+  const wanted = datasourceKey === undefined || datasourceKey === null || String(datasourceKey).trim() === ''
+    ? ''
+    : String(datasourceKey).trim();
+  return keyedGetEvidence(envelope).some(evidence => {
+    if (evidence.ok !== true || evidence.skipped === true) {
+      return false;
+    }
+    return wanted === '' || String(evidence.datasourceKey || '') === wanted;
+  });
+}
+
 /**
  * @param {Object|null|undefined} envelope - DatasourceTestRun-like
  * @param {string|undefined|null} requestedCapabilityKey - From positional [capabilityKey]
@@ -23,6 +60,10 @@ function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
     envelope && typeof envelope === 'object' && Array.isArray(envelope.capabilities)
       ? envelope.capabilities
       : [];
+  if (key === 'get' && keyedGetEvidence(envelope).length > 0 &&
+      !hasExecutedKeyedGet(envelope, envelope.datasourceKey)) {
+    return { violated: true, message: 'Capabilities scope: keyed get was not executed successfully.' };
+  }
   if (caps.length <= 1) {
     return { violated: false };
   }
@@ -39,5 +80,7 @@ function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
 }
 
 module.exports = {
-  analyzeCapabilityScope
+  analyzeCapabilityScope,
+  keyedGetEvidence,
+  hasExecutedKeyedGet
 };

package/lib/utils/datasource-test-run-debug-display.js

@@ -4,6 +4,7 @@
  * @version 2.0.0
  */
 
+const { sanitizeBinaryEvidence } = require('./datasource-binary-evidence');
 const { SEP, appendReferenceLayoutLines } = require('./datasource-test-run-display');
 const { buildDebugEnvelopeSlice } = require('./datasource-test-run-debug-slice');
 const {
@@ -250,6 +251,7 @@ function applyRawLineCap(text) {
  * @returns {string}
  */
 function formatDatasourceTestRunDebugBlock(envelope, mode, isTTY) {
+  envelope = sanitizeBinaryEvidence(envelope);
   if (!envelope || typeof envelope !== 'object') return '';
 
   const lines = ['', SEP, `Debug (${mode})`];

package/lib/utils/datasource-test-run-display.js

@@ -5,9 +5,11 @@
  */
 
 const chalk = require('chalk');
+const { binaryEvidenceLines } = require('./datasource-binary-evidence');
 const { sectionTitle, headerKeyValue, colorAggregateGlyph, successGlyph, failureGlyph } = require('./cli-test-layout-chalk');
 const { appendCertificateTTY, appendCertificateIssuanceTTY } = require('./datasource-test-run-certificate-tty');
 const { buildTtyMetaLines: buildTtyMetaLinesCore } = require('./datasource-test-run-tty-meta-lines');
+const { appendStructuredIssueGuidance } = require('./datasource-test-run-issue-guidance');
 
 const SEP = '────────────────────────────────';
 
@@ -297,9 +299,12 @@ function appendValidationIssueLines(lines, envelope, maxIssues = 5) {
   const cap = Math.min(maxIssues, issues.length);
   for (let i = 0; i < cap; i += 1) {
     const iss = issues[i];
-    const code = iss && iss.code ? chalk.red(`[${iss.code}] `) : '';
+    const issueCode = iss && (iss.stableCode || iss.code);
+    const code = issueCode ? chalk.red(`[${issueCode}] `) : '';
+    const severity = iss?.severity ? chalk.gray(`[${String(iss.severity)}] `) : '';
     const msg = iss && iss.message ? String(iss.message) : JSON.stringify(iss);
-    lines.push(`  ${code}${chalk.yellow(msg)}`);
+    lines.push(`  ${code}${severity}${chalk.yellow(msg)}`);
+    appendStructuredIssueGuidance(lines, iss);
     appendDpSec013Details(lines, iss);
   }
   if (issues.length > cap) {
@@ -448,6 +453,7 @@ function formatDatasourceTestRunTTY(envelope, options = {}) {
   appendRefsSectionIfEnabled(lines, envelope, options);
   appendValidationIssueLines(lines, envelope);
   appendIntegrationStepLines(lines, envelope);
+  lines.push(...binaryEvidenceLines(envelope));
   const focus = normalizedFocusCapabilityKey(options.focusCapabilityKey);
   if (focus) {
     lines.push(formatCapabilityFocusSection(envelope, focus));

package/lib/utils/datasource-test-run-issue-guidance.js

@@ -0,0 +1,176 @@
+/**
+ * Structured human guidance for DatasourceTestRun validation issues.
+ *
+ * @fileoverview Preserve actionable issue fields in TTY output
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+
+const STEP_VERBS = {
+  locate_file: 'open',
+  update_path: 'update',
+  add_mapping: 'add mapping',
+  set_value: 'set',
+  remove_value: 'remove',
+  add_item: 'add to',
+  remove_item: 'remove from'
+};
+
+const UPSERT_GUIDANCE = {
+  'DP-CIP-030': {
+    observed: 'The declared upsert does not contain the required create, update, and records-output composition.',
+    consequence: 'The runtime cannot execute one deterministic create-or-update operation.',
+    aiFixable: true,
+    remediation: [
+      'Run aifabrix datasource capability upsert <file-or-key> --overwrite --dry-run, review the patch, then apply and validate it.'
+    ],
+    prevention: 'Author upsert through the capability command and keep both source halves valid.',
+    residualRisk: 'Publication remains blocked while the composition is malformed.',
+    rerun: 'Rerun the same focused datasource validation or E2E case.'
+  },
+  'DP-CIP-031': {
+    observed: 'The upsert declares no usable business identity.',
+    consequence: 'Existence cannot be resolved, so a retry may create a duplicate or update the wrong record.',
+    aiFixable: true,
+    remediation: [
+      'Run aifabrix datasource capability upsert <file-or-key> --identity <fields> --dry-run with author-approved mapped non-primary fields.'
+    ],
+    prevention: 'Model business identity before exposing a composed write.',
+    residualRisk: 'Upsert must remain unavailable until identity is explicit and validated.',
+    rerun: 'Rerun the same focused datasource validation or E2E case.'
+  },
+  'DP-CIP-040': {
+    observed: 'No declared read operation can constrain the complete business identity.',
+    consequence: 'The source record may be missed, creating a duplicate or selecting the wrong update target.',
+    aiFixable: false,
+    remediation: [
+      'Declare a real exact lookup only if the source API supports it.',
+      'Otherwise keep separate create and update capabilities and withhold upsert readiness.'
+    ],
+    prevention: 'Require complete equality lookup coverage before authoring upsert.',
+    residualRisk: 'AI cannot repair a source API that lacks exact lookup or uniqueness.',
+    rerun: 'After a supported lookup is declared, rerun the same focused validation and E2E proof.'
+  },
+  'DP-CIP-041': {
+    observed: 'A covering identity read is declared, but live filtering has not been proven.',
+    consequence: 'Static coverage alone cannot show that the source applies the constraint or exposes writes in time.',
+    aiFixable: false,
+    remediation: ['Run the focused live validation and two-write no-duplicate E2E proof; do not add a duplicate read declaration.'],
+    prevention: 'Keep exact lookup and no-duplicate proof scenarios with every upsert datasource.',
+    residualRisk: 'Read-after-write delay can leave a bounded duplicate window until runtime protection is proven.',
+    rerun: 'Rerun the same focused datasource validation and upsert E2E case.'
+  }
+};
+
+function normalizeOptionalString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function hasGuidanceValue(value) {
+  if (Array.isArray(value)) return value.some(hasGuidanceValue);
+  if (typeof value === 'boolean') return true;
+  if (value && typeof value === 'object') return Object.keys(value).length > 0;
+  return normalizeOptionalString(value) !== '';
+}
+
+function firstGuidanceValue(...values) {
+  return values.find(hasGuidanceValue);
+}
+
+function guidancePayload(item) {
+  return normalizeOptionalString(item.value) || normalizeOptionalString(item.template);
+}
+
+function guidanceVerb(step) {
+  return STEP_VERBS[step] || step.replace(/_/g, ' ') || 'update';
+}
+
+/**
+ * Render one guidance entry, which may be a string or a structured fix instruction.
+ *
+ * `fix.instructions[]` entries are objects ({step, path, value, template, note}),
+ * so stringifying them printed `[object Object]` and the remediation — the part a
+ * developer acts on — was lost.
+ *
+ * @param {unknown} item guidance entry
+ * @returns {string|null} display text, or null when there is nothing to show
+ */
+function formatGuidanceItem(item) {
+  if (typeof item === 'string') return item.trim() || null;
+  if (!item || typeof item !== 'object') return null;
+
+  const step = normalizeOptionalString(item.step);
+  const note = normalizeOptionalString(item.note);
+  const target = normalizeOptionalString(item.path);
+  const payload = guidancePayload(item);
+
+  // `explain` carries no path or value; its note *is* the instruction.
+  if (step === 'explain' || (!target && !payload)) {
+    return note || (step ? step.replace(/_/g, ' ') : null);
+  }
+
+  const verb = guidanceVerb(step);
+  // With no path the payload *is* the target (e.g. locate_file carries a path in
+  // `value`), so it reads as "open <file>" rather than "open: <file>".
+  let text = target ? `${verb} ${target}` : `${verb} ${payload}`;
+  if (target && payload) text += step === 'set_value' ? ` = ${payload}` : `: ${payload}`;
+  return note ? `${text} — ${note}` : text;
+}
+
+function appendGuidanceValue(lines, label, value) {
+  const values = Array.isArray(value) ? value : [value];
+  values
+    .map(formatGuidanceItem)
+    .filter(Boolean)
+    .forEach((text) => {
+      lines.push(`    ${chalk.gray(`${label}:`)} ${chalk.white(text)}`);
+    });
+}
+
+function enrichUpsertIssueGuidance(issue) {
+  if (!issue || typeof issue !== 'object') return issue;
+  const code = issue.stableCode || issue.code;
+  const fallback = UPSERT_GUIDANCE[code];
+  if (!fallback) return issue;
+  const enriched = { ...issue };
+  Object.entries(fallback).forEach(([key, value]) => {
+    if (!hasGuidanceValue(enriched[key])) enriched[key] = value;
+  });
+  return enriched;
+}
+
+function appendStructuredIssueGuidance(lines, issue) {
+  if (!issue || typeof issue !== 'object') return;
+  const display = enrichUpsertIssueGuidance(issue);
+  appendGuidanceValue(lines, 'Observed', firstGuidanceValue(
+    issue.observed, issue.details?.diagnosis, display.observed
+  ));
+  appendGuidanceValue(lines, 'Consequence', firstGuidanceValue(
+    issue.impact, issue.consequence, issue.reason, display.consequence
+  ));
+  if (typeof display.aiFixable === 'boolean') {
+    appendGuidanceValue(lines, 'Can AI fix?', display.aiFixable
+      ? 'Yes — only as an authorized deterministic local manifest change.'
+      : 'No automatic fix is safe for this source or live-proof limitation.');
+  }
+  appendGuidanceValue(lines, 'Safe action', firstGuidanceValue(
+    issue.fix?.instructions, issue.remediation, issue.hint, display.remediation
+  ));
+  appendGuidanceValue(lines, 'Prevention', firstGuidanceValue(
+    issue.prevention, issue.fix?.prevention, display.prevention
+  ));
+  appendGuidanceValue(lines, 'Residual risk', firstGuidanceValue(
+    issue.residualRisk, issue.risk, display.residualRisk
+  ));
+  appendGuidanceValue(lines, 'Rerun', firstGuidanceValue(
+    issue.rerun, issue.fix?.rerun, display.rerun
+  ));
+}
+
+module.exports = {
+  appendStructuredIssueGuidance,
+  enrichUpsertIssueGuidance,
+  formatGuidanceItem
+};

package/lib/utils/datasource-test-run-tty-log.js

@@ -5,6 +5,7 @@
 'use strict';
 
 const chalk = require('chalk');
+const { sanitizeBinaryEvidence } = require('./datasource-binary-evidence');
 const logger = require('./logger');
 const { getReportVersionStderrMessage } = require('./datasource-test-run-report-version');
 const {
@@ -42,6 +43,7 @@ function emitCapabilityScopeDiagnostics(envelope, opts = {}) {
  * @param {string} [options.requestedCapabilityKey]
  */
 function printDatasourceTestRunForTTY(envelope, options = {}) {
+  envelope = sanitizeBinaryEvidence(envelope);
   const mode = resolveDebugDisplayMode(options.debug);
   const displayOpts = {
     focusCapabilityKey: options.requestedCapabilityKey,

package/lib/utils/docker-build.js

@@ -96,8 +96,15 @@ function handleDockerClose(code, ctx) {
   }
 }
 
-function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs, noCache) {
+function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs, options = {}) {
+  const { noCache = false, target } = options;
   const args = ['build', '-t', `${imageName}:${tag}`, '-f', dockerfilePath];
+  // A multi-stage Dockerfile builds its last stage unless told otherwise. `build.target`
+  // lets one Dockerfile serve several images from the same source, which is the only way
+  // an app can ship two variants without duplicating its build.
+  if (target) {
+    args.push('--target', String(target));
+  }
   for (const [key, value] of Object.entries(buildArgs)) {
     if (value !== null && value !== undefined && String(value).length > 0) {
       args.push('--build-arg', `${key}=${String(value)}`);
@@ -111,9 +118,12 @@ function buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildAr
 }
 
 function createDockerSpawnParams(options) {
-  const { imageName, tag, dockerfilePath, contextPath, buildArgs, noCache, env } = options;
+  const { imageName, tag, dockerfilePath, contextPath, buildArgs, noCache, env, target } = options;
   const spawnEnv = { ...process.env, ...(env || {}) };
-  const args = buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs || {}, noCache);
+  const args = buildDockerCliArgs(imageName, tag, dockerfilePath, contextPath, buildArgs || {}, {
+    noCache,
+    target
+  });
   return { spawnEnv, args };
 }
 
@@ -163,7 +173,8 @@ function runDockerBuildProcess(buildOpts) {
     reject,
     env = {},
     buildArgs = {},
-    noCache = false
+    noCache = false,
+    target
   } = buildOpts;
   const { spawnEnv, args } = createDockerSpawnParams({
     imageName,
@@ -172,7 +183,8 @@ function runDockerBuildProcess(buildOpts) {
     contextPath,
     buildArgs,
     noCache,
-    env
+    env,
+    target
   });
   const dockerProcess = spawn('docker', args, {
     shell: process.platform === 'win32',
@@ -192,7 +204,12 @@ function runDockerBuildProcess(buildOpts) {
  * @returns {Promise<void>} Resolves when build completes
  * @throws {Error} If build fails
  */
-async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}, noCache = false) {
+async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs = {}, options = false) {
+  // Historically the sixth argument was the `noCache` boolean. It is now an options
+  // object so a build stage can be named too; the boolean form still works, because
+  // this function is exported and callers outside this module pass it that way.
+  const { noCache = false, target } =
+    typeof options === 'boolean' ? { noCache: options } : options || {};
   const spinner = ora({ text: 'Starting Docker build...', spinner: 'dots' }).start();
   const fsSync = require('fs');
   const path = require('path');
@@ -228,7 +245,8 @@ async function executeDockerBuild(imageName, dockerfilePath, contextPath, tag, b
       reject,
       env: dockerCliEnv,
       buildArgs: resolvedBuildArgs,
-      noCache
+      noCache,
+      target
     });
   });
 }
@@ -251,7 +269,10 @@ async function executeBuild(imageName, dockerfilePath, contextPath, tag, options
     options &&
       (options.cache === false || options.noCache === true || options['no-cache'] === true)
   );
-  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, noCache);
+  await executeDockerBuild(imageName, dockerfilePath, contextPath, tag, buildArgs, {
+    noCache,
+    target: options && options.target
+  });
   await applyTagAliases(imageName, tag, resolveTagAliases(tag, options));
 }
 

package/lib/utils/docker-manifest-public-port.js

@@ -81,6 +81,41 @@ async function mergeDockerManifestPublishedPort(envVars, appDoc) {
   envVars[publicPortKey] = String(devIdNum > 0 ? pubBase + devIdNum * 100 : pubBase);
 }
 
+/**
+ * Publish `<NAME>_PUBLIC_PORT` for every `additionalPorts` entry.
+ *
+ * An application serving a second protocol needs to tell clients which port to use, and
+ * that is the *published* host port, not the one it listens on inside the container. The
+ * two differ by the developer-id offset, so a template that types the number by hand
+ * silently disagrees with the manifest the moment either changes — and the application
+ * then advertises a port nothing is listening on.
+ *
+ * Named after the port, so `additionalPorts: [{ name: ssh, hostPort: 2200 }]` gives
+ * `SSH_PUBLIC_PORT`, which an env.template consumes as `${SSH_PUBLIC_PORT}`.
+ *
+ * @param {Object} envVars - Mutated map from buildEnvVarMap
+ * @param {Object|null|undefined} appDoc - application.yaml root
+ * @returns {Promise<void>}
+ */
+async function mergeAdditionalPublishedPorts(envVars, appDoc) {
+  const entries = appDoc && Array.isArray(appDoc.additionalPorts) ? appDoc.additionalPorts : [];
+  if (entries.length === 0) {
+    return;
+  }
+  const devIdNum = await require('./env-map').getDeveloperIdNumber(null);
+  for (const entry of entries) {
+    if (!entry || typeof entry.name !== 'string') {
+      continue;
+    }
+    const base = Number(entry.hostPort);
+    if (!Number.isFinite(base)) {
+      continue;
+    }
+    const key = `${entry.name.trim().toUpperCase().replace(/-/g, '_')}_PUBLIC_PORT`;
+    envVars[key] = String(devIdNum > 0 ? base + devIdNum * 100 : base);
+  }
+}
+
 /**
  * Rewrite first line for the matched *_PUBLIC_PORT after interpolateEnvVars (early kv pass may have wrong value).
  * @param {string} resolved
@@ -111,6 +146,7 @@ function rewriteDockerManifestPublicPortEnvLine(resolved, envVars, appDoc) {
 module.exports = {
   findDockerHostKeyForAppKey,
   publicPortKeyForAppKey,
+  mergeAdditionalPublishedPorts,
   mergeDockerManifestPublishedPort,
   rewriteDockerManifestPublicPortEnvLine
 };