@aifabrix/builder 2.58.0 → 2.59.0

package/lib/deployment/installation/environment-auth.js

@@ -2,8 +2,8 @@
 
 /**
  * @fileoverview Controller URL and Bearer authentication for dev/tst/pro workspace stages.
- * Order: explicit `--miso-api-key-env` selector, `MISO_API_KEY` from the process, the workspace
- * `.env`/secret system, then an existing Controller login. Key values never appear in output.
+ * Order: exclusive explicit selector, otherwise Controller login, process key, then
+ * workspace `.env`/secret system. Key values never appear in output.
  */
 
 const { validateControllerUrl } = require('../../utils/deployment-validation');
@@ -40,37 +40,77 @@ async function workspaceApiKey(workspace, secretsApi) {
 }
 
 /**
- * Resolves Bearer authentication for Miso environment calls.
- * @param {Object} params - Inputs
- * @param {Object} params.workspace - Opened workspace
- * @param {string} params.controllerUrl - Controller URL
- * @param {string} [params.keyEnvName] - Explicit environment-variable selector
- * @param {Object} [params.deps] - Injected getDeviceToken/secretsApi/env
- * @returns {Promise<{ authConfig: Object, source: string }>}
+ * Lazily yield credentials without resolving lower-priority secrets unnecessarily.
+ * @param {Object} params - Workspace, controller URL, selector and dependencies
+ * @yields {Object} Authentication candidate
  */
-async function resolveEnvironmentAuth({ workspace, controllerUrl, keyEnvName, deps = {} }) {
+async function* environmentAuthCandidates({ workspace, controllerUrl, keyEnvName, deps = {} }) {
   const processEnv = deps.env || process.env;
   if (keyEnvName) {
     const value = processEnv[keyEnvName];
     if (!value) throw new Error(`Environment variable ${keyEnvName} selected by --miso-api-key-env is not set`);
-    return { authConfig: { type: 'bearer', token: value }, source: 'selector' };
+    yield { authConfig: { type: 'bearer', token: value }, source: 'selector' };
+    return;
+  }
+  const getDeviceToken = deps.getDeviceToken || require('../../utils/token-manager').getOrRefreshDeviceToken;
+  const device = await getDeviceToken(controllerUrl);
+  if (device?.token) {
+    yield { authConfig: { type: 'bearer', token: device.token, controller: controllerUrl }, source: 'login' };
   }
   if (processEnv.MISO_API_KEY) {
-    return { authConfig: { type: 'bearer', token: processEnv.MISO_API_KEY }, source: 'process' };
+    yield { authConfig: { type: 'bearer', token: processEnv.MISO_API_KEY }, source: 'process' };
   }
   const fromWorkspace = await workspaceApiKey(workspace, deps.secretsApi);
-  if (fromWorkspace) {
-    return { authConfig: { type: 'bearer', token: fromWorkspace }, source: 'workspace' };
+  if (fromWorkspace) yield { authConfig: { type: 'bearer', token: fromWorkspace }, source: 'workspace' };
+}
+
+/**
+ * Normalize preflight failures without exposing server-echoed credentials.
+ * @param {Function} validateAuth - Initial read-only request
+ * @param {Object} auth - Candidate auth config
+ * @returns {Promise<Object>} API response (only 401 permits fallback)
+ */
+async function validateCandidate(validateAuth, auth) {
+  let response;
+  try {
+    response = await validateAuth(auth);
+  } catch (error) {
+    const status = error?.status ?? error?.statusCode;
+    response = { success: false, status: Number.isInteger(status) ? status : undefined };
   }
-  const getDeviceToken = deps.getDeviceToken || require('../../utils/token-manager').getOrRefreshDeviceToken;
-  const device = await getDeviceToken(controllerUrl);
-  if (device && device.token) {
-    return { authConfig: { type: 'bearer', token: device.token, controller: controllerUrl }, source: 'login' };
+  if (response?.success === true || response?.status === 401) return response;
+  const status = Number.isInteger(response?.status) ? response.status : undefined;
+  const error = new Error(`Miso tenant status failed${status ? ` (HTTP ${status})` : ''}. Check Controller connectivity and permissions.`);
+  error.status = status;
+  throw error;
+}
+
+/**
+ * Resolve auth, optionally selecting it through the initial read-only preflight.
+ * @param {Object} params - Workspace, controllerUrl, keyEnvName and injected deps
+ * @param {Function} [params.validateAuth] - Read-only request returning an API response
+ * @returns {Promise<Object>} Selected auth/source and optional validationResponse
+ */
+async function resolveEnvironmentAuth(params) {
+  const seen = new Set();
+  for await (const candidate of environmentAuthCandidates(params)) {
+    if (seen.has(candidate.authConfig.token)) continue;
+    seen.add(candidate.authConfig.token);
+    if (!params.validateAuth) return candidate;
+    const response = await validateCandidate(params.validateAuth, candidate.authConfig);
+    if (response.success === true) return { ...candidate, validationResponse: response };
+    if (candidate.source === 'selector') {
+      const error = new Error('Explicit Controller key rejected (HTTP 401). Check --miso-api-key-env; no other credential was tried.');
+      error.status = 401;
+      throw error;
+    }
   }
-  throw new Error(
-    `No Controller authentication for ${controllerUrl}. Run "aifabrix login -c ${controllerUrl}", ` +
+  const error = new Error(
+    `No Controller authentication for ${params.controllerUrl}. Run "aifabrix login -c ${params.controllerUrl}", ` +
     'or set MISO_API_KEY (or --miso-api-key-env <NAME>) to a temporary installation key.'
   );
+  error.status = 401;
+  throw error;
 }
 
 module.exports = { resolveControllerUrl, resolveEnvironmentAuth };

package/lib/deployment/installation/environment-stage.js

@@ -14,6 +14,9 @@ const { buildEnvironmentDocument, buildMisoRequests, refreshVariableCatalog } =
 const { readWorkspaceEnv, removeWorkspaceEnvKey } = require('./workspace-env');
 const { resolveControllerUrl, resolveEnvironmentAuth } = require('./environment-auth');
 
+const logger = require('../../utils/logger');
+const { metadata } = require('../../utils/cli-test-layout-chalk');
+
 const FAILED_STATES = Object.freeze(['failed', 'error', 'cancelled']);
 
 function defaultApi() {
@@ -34,8 +37,7 @@ function apiFailure(step, response) {
   return error;
 }
 
-async function assertTenantActive(ctx) {
-  const response = await ctx.api.getTenantStatus(ctx.controllerUrl, ctx.auth);
+async function assertTenantActive(ctx, response) {
   if (!response.success) throw apiFailure('tenant status', response);
   const status = String(payload(response)?.status || 'UNKNOWN').toUpperCase();
   const recorded = ['PENDING', 'ACTIVE', 'INACTIVE'].includes(status) ? status.toLowerCase() : 'unknown';
@@ -169,11 +171,13 @@ async function runEnvironmentStage(workspace, input, deps = {}) {
   const { envDoc, requests } = prepareEnvironmentDocument(ctx, input, env);
   ctx.controllerUrl = resolveControllerUrl({ envDoc, infra: ctx.infra, env, override: input.controllerUrl });
   saveEnvironment(ctx.workspace, ctx.envKey, envDoc);
-  const { authConfig, source } = await resolveEnvironmentAuth({
-    workspace, controllerUrl: ctx.controllerUrl, keyEnvName: input.misoApiKeyEnv, deps: { ...deps, env: ctx.processEnv }
+  const { authConfig, source, validationResponse } = await resolveEnvironmentAuth({
+    workspace, controllerUrl: ctx.controllerUrl, keyEnvName: input.misoApiKeyEnv, deps: { ...deps, env: ctx.processEnv },
+    validateAuth: auth => ctx.api.getTenantStatus(ctx.controllerUrl, auth)
   });
   ctx.auth = authConfig;
-  await assertTenantActive(ctx);
+  await assertTenantActive(ctx, validationResponse);
+  logger.log(metadata(`Controller authentication source: ${source}`));
   const change = await createOrUpdate(ctx, requests);
   await validateRequest(ctx, requests.deploy);
   const { deploymentId, resumed } = await submitDeployment(ctx, requests.deploy);

package/lib/deployment/installation/infra-catalog.js

@@ -95,8 +95,11 @@ const PARAMETER_CATALOG = Object.freeze({
   acrAdminUsername: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Empty in the workspace; credential mode fills it only in the temporary ARM parameters file (never committed).' },
   acrAdminPassword: { kind: 'fixed', value: '', source: 'managedIdentityMode', description: 'Empty in the workspace; credential mode fills it only in the temporary ARM parameters file (never committed).' },
   acrResourceId: { kind: 'acrLookup', field: 'id', description: 'Resolved from acrName; mi mode grants AcrPull to both web app identities.' },
-  deployRoleAssignments: { kind: 'file', source: 'templateDefault', description: 'Deploy required Azure role assignments (false while credential image pull is in effect; restored for managed identity).' },
+  deployRoleAssignments: { kind: 'file', source: 'templateDefault', description: 'Deploy Contributor role assignments in the installation resource group. Needed in every mode: without it the controller cannot create the environment resources its second stage deploys.' },
+  deployRegistryRoleAssignment: { kind: 'parameterDefault', defaultFrom: 'deployRoleAssignments', source: 'templateDefault', description: 'Deploy the AcrPull grant on the container registry. False while credential image pull is in effect, because that grant lives in the registry resource group, which a customer installation cannot reach; restored for managed identity.' },
   moriBaseUrl: { kind: 'file', source: 'registration', required: true, description: 'Mori service base URL.' },
+  moriLicensePublicKey: { kind: 'file', source: 'registration', required: false, description: 'Mori licence issuer public key (SPKI PEM); empty leaves the installation unpinned and it then refuses every licence.' },
+  moriLicenseIssuer: { kind: 'file', source: 'registration', required: false, description: 'Expected iss claim on a Mori licence.' },
   moriCallbackApiKey: { kind: 'secretEnv', env: 'MORI_CALLBACK_API_KEY', required: true, description: 'Mori callback authentication key.' },
   entraCallbackStateSecret: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdClientId: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
@@ -104,6 +107,7 @@ const PARAMETER_CATALOG = Object.freeze({
   entraIdTenantId: { kind: 'deferred', description: 'Customer Entra provider tenant; distinct from the Azure subscription directory tenant and configured later.' },
   licenseEdition: { kind: 'license', source: 'cliOrFile', description: 'License requested from Mori during tenant activation: COMMUNITY, STANDARD or ENTERPRISE, or an Azure Marketplace subscription ID. Standard/Enterprise by name is a 30-day evaluation.' },
   onboardingMode: { kind: 'onboarding', source: 'workspacePolicy', description: 'Miso onboarding mode (ONBOARDING_MODE); Builder installations use saasDirect, Marketplace customer installations use customerOwned.' },
+  capacityProfile: { kind: 'capacity', source: 'workspacePreset', description: 'Infrastructure sizing profile (s, m, l, xl) selecting compute and PostgreSQL SKUs. Derived from the workspace preset so the two cannot drift; set it with --preset.' },
   misoImageTag: { kind: 'file', source: 'templateDefault', description: 'Miso container image tag.' },
   keycloakImageTag: { kind: 'file', source: 'templateDefault', description: 'Keycloak container image tag.' }
 });
@@ -127,7 +131,9 @@ const OUTPUT_CATALOG = Object.freeze({
   keycloakWebAppUrl: 'Keycloak web application URL.',
   keycloakRealmUrl: 'Keycloak realm URL.',
   keycloakAdminUser: 'Keycloak administrator user name.',
-  portalUrl: 'Azure portal link for the installation resource group.'
+  portalUrl: 'Azure portal link for the installation resource group.',
+  azureOpenAiCreated: 'Whether Phase-1 created the Azure OpenAI account in the installation region.',
+  azureOpenAiSkipReason: 'Why Azure OpenAI was not created; empty when it was. An unsupported region skips the optional account instead of relocating it.'
 });
 
 /** Mori service key name written by DOCKER registration. */

package/lib/deployment/installation/infra-manifest.js

@@ -42,6 +42,11 @@ function parameterEntry(name, template) {
     return entry(DEFAULT_LICENSE_EDITION, spec.source, spec.description);
   case 'onboarding':
     return entry(DEFAULT_ONBOARDING_MODE, spec.source, spec.description);
+  case 'capacity':
+    // Mirrors the workspace preset; azure-infra-stage keeps them in step on every run.
+    return entry('s', spec.source, spec.description);
+  case 'parameterDefault':
+    return entry(templateDefault(template, spec.defaultFrom), spec.source, spec.description);
   default:
     return entry(templateDefault(template, name), spec.source, spec.description, spec.required ? { required: true } : {});
   }

package/lib/deployment/installation/registry-auth-mode.js

@@ -13,6 +13,22 @@ const { ACR_AUTH_DESCRIPTION } = require('./infra-manifest');
 
 const FORCED_ROLE_SOURCES = Object.freeze(['acrAuthCredentials', 'acrAuthAdmin']);
 
+function restoreForcedRole(roles) {
+  const { restoreValue, restoreSource, ...rest } = roles;
+  return {
+    ...rest,
+    value: restoreValue === undefined ? true : restoreValue,
+    source: restoreSource || 'templateDefault'
+  };
+}
+
+function restoreLegacyContributorRole(doc) {
+  const roles = doc.parameters.deployRoleAssignments;
+  if (roles && FORCED_ROLE_SOURCES.includes(roles.source)) {
+    doc.parameters.deployRoleAssignments = restoreForcedRole(roles);
+  }
+}
+
 /**
  * Normalizes and records the requested mode (CLI wins over the workspace value).
  * @param {Object} doc - Infra manifest (mutated)
@@ -62,29 +78,36 @@ async function resolveRegistryAuth(doc, acr, az, deps) {
 }
 
 /**
- * Records the effective mode and keeps role assignments consistent with it. Credential mode turns
- * ARM role assignments off; returning to managed identity restores the value it replaced.
+ * Records the effective mode and keeps the registry role assignment consistent with it.
+ *
+ * Credential mode turns off only `deployRegistryRoleAssignment` -- the AcrPull grant, which lives
+ * in the registry's own resource group and, for a customer installation, in the vendor's tenant
+ * where Azure RBAC cannot reach. It deliberately leaves `deployRoleAssignments` alone: those are
+ * Contributor grants in the resource group the installation is creating, which the deployer owns.
+ *
+ * Turning both off is what ce-12 and ce-13 did, and it broke the installation in a way that took
+ * two attempts to see. Without Contributor on its own resource group the controller cannot create
+ * anything, so its second stage failed every module, no resource bindings were recorded, and both
+ * application deployments refused with "Environment 'dev' has no recorded placement".
+ *
  * @param {Object} doc - Infra manifest (mutated)
  * @param {'mi'|'credentials'} mode - Effective mode
  */
 function applyEffectiveAcrAuth(doc, mode) {
   doc.acrAuth = { ...doc.acrAuth, effective: mode };
-  const roles = doc.parameters.deployRoleAssignments;
+  restoreLegacyContributorRole(doc);
+  const roles = doc.parameters.deployRegistryRoleAssignment
+    || doc.parameters.deployRoleAssignments;
   const forced = FORCED_ROLE_SOURCES.includes(roles.source);
   if (mode === 'credentials') {
     if (forced) return;
-    doc.parameters.deployRoleAssignments = {
+    doc.parameters.deployRegistryRoleAssignment = {
       ...roles, value: false, source: 'acrAuthCredentials', restoreValue: roles.value, restoreSource: roles.source
     };
     return;
   }
   if (!forced) return;
-  const { restoreValue, restoreSource, ...rest } = roles;
-  doc.parameters.deployRoleAssignments = {
-    ...rest,
-    value: restoreValue === undefined ? true : restoreValue,
-    source: restoreSource || 'templateDefault'
-  };
+  doc.parameters.deployRegistryRoleAssignment = restoreForcedRole(roles);
 }
 
 /**

package/lib/deployment/marketplace-environment.js

@@ -9,6 +9,7 @@ const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const config = require('../core/config');
 const { getRuntimeConfigDir } = require('../core/config-runtime-paths');
+const logger = require('../utils/logger');
 
 const SHIPPED_TEMPLATE = path.resolve(__dirname, '../../templates/marketplace/main.json');
 // Resolved per call (not a module-load constant) so it honors AIFABRIX_HOME/AIFABRIX_CONFIG
@@ -273,8 +274,28 @@ async function deployMarketplaceEnvironment(envKey, options, dependencies = {})
   return deployPlatform({ ...input, controllerUrl: options.controllerUrl }, dependencies);
 }
 
+/**
+ * Attempts allowed for the controller, at 10-second intervals.
+ *
+ * The controller runs first-time onboarding inside startup, and on Azure that onboarding is
+ * normally interrupted once — the template applies post-Key-Vault app settings and restarts the
+ * site — so the retry runs too. A clean installation was measured taking 720 seconds to pass its
+ * warm-up probe. The old 30 attempts gave 5 minutes and reported `readiness did not pass` for
+ * installations that were healthy, which is worse than a slow wait: it leaves `controllerUrl`
+ * unrecorded, so `--stage dev` then refuses with "Shared infrastructure is not deployed".
+ *
+ * 180 attempts is 30 minutes, matching WEBSITES_CONTAINER_START_TIME_LIMIT. Waiting longer than
+ * App Service itself would is pointless; waiting less than it declares is what caused this.
+ */
+const CONTROLLER_READINESS_ATTEMPTS = 180;
+
 async function probeController(controllerUrl) {
-  return probeHttps(controllerUrl, '/api/v1/health/readiness', 'Controller');
+  return probeHttps(
+    controllerUrl,
+    '/api/v1/health/readiness',
+    'Controller',
+    CONTROLLER_READINESS_ATTEMPTS
+  );
 }
 
 /**
@@ -297,6 +318,10 @@ async function probeHttps(baseUrl, pathname, label, attempts = 30) {
     } catch (_) {
       // App Service startup can lag successful ARM provisioning.
     }
+    // A wait measured in minutes should say so, or it is indistinguishable from a hang.
+    if (attempt > 0 && attempt % 6 === 0) {
+      logger.log(`  waiting for ${label} readiness… ${attempt * 10}s elapsed`);
+    }
     await new Promise(resolve => setTimeout(resolve, 10000));
   }
   throw new Error(`${label} readiness did not pass at ${url.origin}; inspect App Service before resuming`);

package/lib/generator/index.js

@@ -117,35 +117,46 @@ function substitutePortInDeployment(obj, portNumber) {
 /** Regex to find ${VAR} placeholders for env substitution */
 const ENV_VAR_PLACEHOLDER_REGEX = /\$\{([^}]+)\}/g;
 
+function replaceDeploymentEnvString(value, envVarMap, fieldPath) {
+  if (fieldPath === 'frontDoorRouting.host') return value;
+  return value.replace(ENV_VAR_PLACEHOLDER_REGEX, (match, varName) =>
+    Object.prototype.hasOwnProperty.call(envVarMap, varName) ? String(envVarMap[varName]) : match);
+}
+
+function substituteEnvVarsInArray(items, envVarMap, fieldPath) {
+  for (let i = 0; i < items.length; i++) {
+    const itemPath = `${fieldPath}[${i}]`;
+    if (typeof items[i] === 'string') {
+      items[i] = replaceDeploymentEnvString(items[i], envVarMap, itemPath);
+    } else if (typeof items[i] === 'object' && items[i] !== null) {
+      substituteEnvVarsInDeployment(items[i], envVarMap, itemPath);
+    }
+  }
+}
+
 /**
  * Recursively replaces ${VAR} with envVarMap[VAR] in all string values of obj (in-place).
  * Only substitutes when VAR is a key in envVarMap (from env-config.yaml / config).
  *
  * @param {Object} obj - Deployment manifest or any nested object
  * @param {Object} envVarMap - Flat map of variable names to values (e.g. from buildEnvVarMap('docker'))
+ * @param {string} [fieldPath=''] - Internal traversal path used to preserve the portable front door host template
  */
-function substituteEnvVarsInDeployment(obj, envVarMap) {
+function substituteEnvVarsInDeployment(obj, envVarMap, fieldPath = '') {
   if (!envVarMap || typeof envVarMap !== 'object') return;
   if (obj === null || obj === undefined) return;
   if (Array.isArray(obj)) {
-    for (let i = 0; i < obj.length; i++) {
-      if (typeof obj[i] === 'string') {
-        obj[i] = obj[i].replace(ENV_VAR_PLACEHOLDER_REGEX, (match, varName) =>
-          Object.prototype.hasOwnProperty.call(envVarMap, varName) ? String(envVarMap[varName]) : match);
-      } else if (typeof obj[i] === 'object' && obj[i] !== null) {
-        substituteEnvVarsInDeployment(obj[i], envVarMap);
-      }
-    }
+    substituteEnvVarsInArray(obj, envVarMap, fieldPath);
     return;
   }
   if (typeof obj === 'object') {
     for (const key of Object.keys(obj)) {
       const value = obj[key];
+      const childPath = fieldPath ? `${fieldPath}.${key}` : key;
       if (typeof value === 'string') {
-        obj[key] = value.replace(ENV_VAR_PLACEHOLDER_REGEX, (match, varName) =>
-          Object.prototype.hasOwnProperty.call(envVarMap, varName) ? String(envVarMap[varName]) : match);
+        obj[key] = replaceDeploymentEnvString(value, envVarMap, childPath);
       } else if (typeof value === 'object' && value !== null) {
-        substituteEnvVarsInDeployment(value, envVarMap);
+        substituteEnvVarsInDeployment(value, envVarMap, childPath);
       }
     }
   }

package/lib/integration-definition/apply.js

@@ -18,6 +18,7 @@ const { applyStaticAndEnterprise } = require('./apply-static-enterprise');
 const { applyViewpointDefaults } = require('./apply-viewpoint-defaults');
 const { stampCredentialTestEndpoint } = require('./apply-test-endpoint');
 const { buildSystemFile } = require('./apply-system-file');
+const { resolveAuthoredDatasourceSync } = require('../datasource/sync-defaults');
 
 const STAMP_FILE = '.aifabrix-integration-definition.json';
 
@@ -160,8 +161,7 @@ function buildDatasourceFile(ds, systemKey, capabilities, sync, enrichOptions =
     ...(ds.storageType ? { storageType: ds.storageType } : {}),
     ...(ds.dimensions && typeof ds.dimensions === 'object' ? { dimensions: ds.dimensions } : {}),
     capabilities: buildDatasourceCapabilities(caps, key),
-    // Schema sync is mode/schedule/batchSize only; BID sync.mode=incremental is operational intent.
-    sync: { mode: 'pull', schedule: /** @type {any} */ (sync).schedule || '0 */6 * * *', batchSize: 100 },
+    sync: resolveAuthoredDatasourceSync(ds, sync),
     primaryKey: ['id'],
     labelKey: [labelField],
     ...buildDatasourceSchema(labelField)

package/lib/internal/fs-real-sync.js

@@ -178,5 +178,8 @@ module.exports = {
   rmSync,
   unlinkSync,
   copyFileSync,
-  appendFileSync
+  appendFileSync,
+  openSync: (...args) => delegate('openSync', args),
+  closeSync: (...args) => delegate('closeSync', args),
+  realpathSync: (...args) => delegate('realpathSync', args)
 };

package/lib/programmatic/bearer-auth.js

@@ -8,8 +8,7 @@
 
 'use strict';
 
-/** @type {import('@aifabrix/miso-client').MisoClient | null} */
-let misoClientSingleton = null;
+const { getBuilderMisoRuntime } = require('./builder-miso-runtime');
 
 /**
  * @param {import('http').IncomingMessage} req
@@ -36,65 +35,10 @@ function assertNoForbiddenAuthHeaders(req) {
 }
 
 /**
- * @returns {string}
- */
-function resolveControllerUrlFromEnv() {
-  const raw =
-    process.env.MISO_CONTROLLER_URL ||
-    process.env.CONTROLLER_URL ||
-    process.env.MISO_WEB_SERVER_URL ||
-    '';
-  const url = String(raw).trim().replace(/\/$/, '');
-  if (!url) {
-    throw new Error('MISO_CONTROLLER_URL (or CONTROLLER_URL) is required for token validation');
-  }
-  return url;
-}
-
-/**
- * @returns {import('@aifabrix/miso-client/dist/types/config.types').MisoClientConfig}
- */
-function buildMisoClientConfigFromEnv() {
-  const clientId = (process.env.MISO_CLIENTID || '').trim();
-  const clientSecret = (process.env.MISO_CLIENTSECRET || '').trim();
-  if (!clientId || !clientSecret) {
-    throw new Error('MISO_CLIENTID and MISO_CLIENTSECRET are required for builder-api auth');
-  }
-  return {
-    clientId,
-    clientSecret,
-    controllerUrl: resolveControllerUrlFromEnv(),
-    logLevel: (process.env.LOG_LEVEL || 'info').toLowerCase()
-  };
-}
-
-/**
- * Test hook — reset cached MisoClient between Jest cases.
- */
-function resetMisoClientForTests() {
-  misoClientSingleton = null;
-}
-
-/**
- * @returns {Promise<import('@aifabrix/miso-client').MisoClient>}
+ * @returns {Promise<import('@aifabrix/miso-client').MisoClient>} Initialized shared client
  */
 async function getMisoClientForAuth() {
-  let MisoClient;
-  try {
-    ({ MisoClient } = require('@aifabrix/miso-client'));
-  } catch {
-    const err = new Error('@aifabrix/miso-client is required for builder-api auth');
-    err.statusCode = 503;
-    throw err;
-  }
-
-  if (!misoClientSingleton) {
-    misoClientSingleton = new MisoClient(buildMisoClientConfigFromEnv());
-  }
-  if (!misoClientSingleton.isInitialized()) {
-    await misoClientSingleton.initialize();
-  }
-  return misoClientSingleton;
+  return getBuilderMisoRuntime().getClient();
 }
 
 /**
@@ -167,9 +111,6 @@ async function authenticateRequest(req, opts = {}) {
 module.exports = {
   extractBearerToken,
   assertNoForbiddenAuthHeaders,
-  resolveControllerUrlFromEnv,
-  buildMisoClientConfigFromEnv,
-  resetMisoClientForTests,
   getMisoClientForAuth,
   validateBearerToken,
   authenticateRequest

package/lib/programmatic/builder-api-startup.js

@@ -0,0 +1,51 @@
+/** @fileoverview Await SDK bootstrap and token proof before accepting requests. */
+'use strict';
+
+const { initializeBuilderMisoRuntime, closeBuilderMisoRuntime } = require('./builder-miso-runtime');
+const { ensureBuilderApiRuntimeConfigDir } = require('./builder-api-runtime-config');
+
+/** @param {Object} server HTTP server @returns {Promise<void>} Listener closed */
+function closeServer(server) {
+  return new Promise(resolve => {
+    server.close(resolve);
+    server.closeAllConnections();
+  });
+}
+
+/**
+ * @param {Object} [options] Startup dependencies
+ * @returns {Promise<{server: Object, close: Function}>} Running application
+ */
+async function startBuilderApi(options = {}) {
+  ensureBuilderApiRuntimeConfigDir();
+  let server;
+  let closing;
+  const close = () => {
+    if (!closing) {
+      closing = Promise.all([server ? closeServer(server) : undefined, closeBuilderMisoRuntime()]);
+    }
+    return closing;
+  };
+  try {
+    const runtime = await initializeBuilderMisoRuntime(options.initSecrets);
+    await runtime.health();
+    const createServer = options.createServer || require('./builder-api-server').createBuilderApiServer;
+    server = createServer(options.port ?? Number(process.env.PORT || 3005));
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.once('listening', () => {
+        server.removeListener('error', reject); resolve();
+      });
+    });
+    return { server, close };
+  } catch (error) {
+    await close().catch(() => {});
+    // Only our allowlisted health errors can cross the process boundary.
+    const failure = new Error('Builder API startup failed: Miso application runtime or authentication unavailable');
+    failure.statusCode = 503;
+    if (error?.statusCode === 503 && error?.errorType?.startsWith('/Errors/miso_')) throw error;
+    throw failure;
+  }
+}
+
+module.exports = { startBuilderApi };