@aifabrix/builder 2.56.0 → 2.58.0

package/lib/deployment/installation/azure-preflight.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE infra preflight before any Azure mutation: active account equals the
+ * workspace subscription/tenant, `acrName` resolves inside that subscription, and the caller can
+ * create deployments. Managed-identity mode also requires role-assignment and AcrPull authority;
+ * password mode fetches ACR admin credentials instead. Uses only the operator's Azure CLI session.
+ */
+
+const ROLE_ASSIGNMENT_WRITE = 'Microsoft.Authorization/roleAssignments/write';
+const DEPLOYMENT_WRITE = 'Microsoft.Resources/deployments/write';
+const PERMISSIONS_API = '2022-04-01';
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    throw new Error(`Azure CLI returned an unreadable ${label} response`);
+  }
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @returns {boolean} True when image pull uses registry username/password (effective mode)
+ */
+function isAdminAcrAuth(doc) {
+  return doc.acrAuth?.effective === 'credentials';
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @param {Function} az - Azure CLI runner
+ * @throws {Error} When the active account differs from the workspace target
+ */
+function assertActiveAccount(doc, az) {
+  const account = parseJson(az(['account', 'show', '--output', 'json']), 'account');
+  const expectedSub = String(doc.subscriptionId.value).toLowerCase();
+  const expectedTenant = String(doc.tenantId.value).toLowerCase();
+  if (String(account.id).toLowerCase() !== expectedSub || String(account.tenantId).toLowerCase() !== expectedTenant) {
+    throw new Error(
+      `Active Azure account (subscription ${account.id}, tenant ${account.tenantId}) does not match the workspace ` +
+      `(subscription ${doc.subscriptionId.value}, tenant ${doc.tenantId.value}). ` +
+      `Run "az login --tenant ${doc.tenantId.value}" and "az account set --subscription ${doc.subscriptionId.value}".`
+    );
+  }
+}
+
+/**
+ * Resolves `acrName` to its resource ID and login server within the workspace subscription.
+ * @param {Object} doc - Infra manifest
+ * @param {Function} az - Azure CLI runner
+ * @returns {{ id: string, loginServer: string, adminUserEnabled: boolean }}
+ */
+function resolveAcr(doc, az) {
+  const subscription = String(doc.subscriptionId.value);
+  const acr = parseJson(az([
+    'acr', 'show', '--name', doc.acrName.value, '--subscription', subscription, '--output', 'json'
+  ]), 'registry');
+  if (typeof acr.id !== 'string' || typeof acr.loginServer !== 'string' || !acr.loginServer) {
+    throw new Error(`Registry ${doc.acrName.value} did not return a resource ID and login server`);
+  }
+  if (!acr.id.toLowerCase().startsWith(`/subscriptions/${subscription.toLowerCase()}/`)) {
+    throw new Error(`Registry ${doc.acrName.value} is outside the workspace subscription; use a registry in ${subscription}`);
+  }
+  return { id: acr.id, loginServer: acr.loginServer, adminUserEnabled: acr.adminUserEnabled === true };
+}
+
+/**
+ * Loads ACR admin username/password for password registry auth. Never persists the password.
+ * @param {Object} doc - Infra manifest
+ * @param {{ adminUserEnabled?: boolean }} acr - Resolved registry metadata
+ * @param {Function} az - Azure CLI runner
+ * @returns {{ username: string, password: string }}
+ */
+function resolveAcrAdminCredentials(doc, acr, az) {
+  if (acr.adminUserEnabled !== true) {
+    throw new Error(
+      `Registry ${doc.acrName.value} does not have the admin user enabled; enable admin user on the ACR ` +
+      'or save a local pair with "aifabrix dev set-registry"'
+    );
+  }
+  const creds = parseJson(az([
+    'acr', 'credential', 'show', '--name', doc.acrName.value,
+    '--subscription', String(doc.subscriptionId.value), '--output', 'json'
+  ]), 'registry credentials');
+  const username = typeof creds.username === 'string' ? creds.username : '';
+  const password = Array.isArray(creds.passwords)
+    ? (creds.passwords.find(item => item && item.value)?.value || '')
+    : '';
+  if (!username || !password) {
+    throw new Error(`Registry ${doc.acrName.value} did not return admin credentials; check ACR admin user access`);
+  }
+  return { username, password };
+}
+
+function actionMatches(pattern, action) {
+  const expression = new RegExp(`^${String(pattern).split('*').map(part => part.replace(/[.+?^${}()|[\]\\/]/g, '\\$&')).join('.*')}$`, 'i');
+  return expression.test(action);
+}
+
+/**
+ * True when Azure RBAC grants `action` at `scope` to the signed-in caller.
+ * @param {Function} az - Azure CLI runner
+ * @param {string} scope - Resource scope ID
+ * @param {string} action - Control-plane action
+ * @returns {boolean}
+ */
+function hasPermission(az, scope, action) {
+  const result = parseJson(az([
+    'rest', '--method', 'get',
+    '--url', `https://management.azure.com${scope}/providers/Microsoft.Authorization/permissions?api-version=${PERMISSIONS_API}`,
+    '--output', 'json'
+  ]), 'permissions');
+  return (result.value || []).some(permission =>
+    (permission.actions || []).some(pattern => actionMatches(pattern, action)) &&
+    !(permission.notActions || []).some(pattern => actionMatches(pattern, action)));
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @param {{ id: string }} acr - Resolved registry
+ * @param {Function} az - Azure CLI runner
+ * @throws {Error} When deployment or (mi) role-assignment authority is missing
+ */
+function assertDeploymentAuthority(doc, acr, az) {
+  const subscriptionScope = `/subscriptions/${doc.subscriptionId.value}`;
+  if (!hasPermission(az, subscriptionScope, DEPLOYMENT_WRITE)) {
+    throw new Error(`The signed-in Azure account cannot create deployments in subscription ${doc.subscriptionId.value}`);
+  }
+  if (isAdminAcrAuth(doc)) return;
+  if (doc.parameters.deployRoleAssignments.value !== false && !hasPermission(az, subscriptionScope, ROLE_ASSIGNMENT_WRITE)) {
+    throw new Error(`The signed-in Azure account cannot create role assignments in subscription ${doc.subscriptionId.value}; ask for Owner or User Access Administrator, or set parameters.deployRoleAssignments.value to false when roles already exist, or use --acr-auth credentials with a pair saved by "aifabrix dev set-registry"`);
+  }
+  if (!hasPermission(az, acr.id, ROLE_ASSIGNMENT_WRITE)) {
+    throw new Error(`The signed-in Azure account cannot assign AcrPull on registry ${doc.acrName.value}; ask for Owner or User Access Administrator on that registry, or use --acr-auth credentials with a pair saved by "aifabrix dev set-registry"`);
+  }
+}
+
+module.exports = {
+  assertActiveAccount,
+  resolveAcr,
+  resolveAcrAdminCredentials,
+  isAdminAcrAuth,
+  hasPermission,
+  actionMatches,
+  assertDeploymentAuthority
+};

package/lib/deployment/installation/azure-readiness.js

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE infra readiness evidence: image pull authorization for both web apps, then
+ * HTTPS probes. Managed-identity mode requires AcrPull + acrUseManagedIdentityCreds; password mode
+ * requires registry credentials on the web app and acrUseManagedIdentityCreds false. Both modes
+ * then require the applications to start (proof that the image was pulled). Local
+ * `az acr login` success is never treated as readiness.
+ */
+
+const { isAdminAcrAuth } = require('./azure-preflight');
+
+const APP_OUTPUTS = Object.freeze([
+  { name: 'webAppName', label: 'Miso' },
+  { name: 'keycloakWebAppName', label: 'Keycloak' }
+]);
+
+function scoped(args, doc) {
+  return [...args, '--subscription', doc.subscriptionId.value];
+}
+
+function verifyManagedIdentityPull(doc, app, acrId, az) {
+  const group = doc.resourceGroup.value;
+  const principalId = az(scoped([
+    'webapp', 'identity', 'show', '--resource-group', group, '--name', app.value,
+    '--query', 'principalId', '--output', 'tsv'
+  ], doc));
+  if (!principalId) throw new Error(`${app.label} web app has no system-assigned identity`);
+  const assignments = az(scoped([
+    'role', 'assignment', 'list', '--scope', acrId, '--role', 'AcrPull',
+    '--query', `length([?principalId=='${principalId}'])`, '--output', 'tsv'
+  ], doc));
+  if (!(Number(assignments) > 0)) {
+    throw new Error(`${app.label} web app identity has no AcrPull assignment on the workspace registry`);
+  }
+  const managedPull = az(scoped([
+    'webapp', 'config', 'show', '--resource-group', group, '--name', app.value,
+    '--query', 'acrUseManagedIdentityCreds', '--output', 'tsv'
+  ], doc));
+  if (String(managedPull).toLowerCase() !== 'true') {
+    throw new Error(`${app.label} web app does not pull images with its managed identity`);
+  }
+}
+
+function verifyPasswordPull(doc, app, az) {
+  const group = doc.resourceGroup.value;
+  const managedPull = az(scoped([
+    'webapp', 'config', 'show', '--resource-group', group, '--name', app.value,
+    '--query', 'acrUseManagedIdentityCreds', '--output', 'tsv'
+  ], doc));
+  if (String(managedPull).toLowerCase() === 'true') {
+    throw new Error(`${app.label} web app still uses managed-identity image pull; expected registry username/password`);
+  }
+  const username = az(scoped([
+    'webapp', 'config', 'appsettings', 'list', '--resource-group', group, '--name', app.value,
+    '--query', '[?name==\'DOCKER_REGISTRY_SERVER_USERNAME\'].value | [0]', '--output', 'tsv'
+  ], doc));
+  if (!username) {
+    throw new Error(`${app.label} web app is missing DOCKER_REGISTRY_SERVER_USERNAME for password registry auth`);
+  }
+}
+
+function verifyAppImagePull(doc, app, acrId, az) {
+  if (isAdminAcrAuth(doc)) {
+    verifyPasswordPull(doc, app, az);
+    return;
+  }
+  verifyManagedIdentityPull(doc, app, acrId, az);
+}
+
+/**
+ * Verifies image-pull authorization for both web apps per acrAuth mode.
+ * @param {Object} doc - Infra manifest with outputs
+ * @param {Function} az - Azure CLI runner
+ */
+function verifyRuntimeImagePull(doc, az) {
+  const acrId = doc.parameters.acrResourceId.value;
+  for (const { name, label } of APP_OUTPUTS) {
+    const value = doc.outputs[name].value;
+    if (!value) throw new Error(`ARM output ${name} is missing; cannot verify ${label} image pull`);
+    verifyAppImagePull(doc, { value, label }, acrId, az);
+  }
+}
+
+/**
+ * Waits for Miso and Keycloak to start after pulling their images.
+ * @param {Object} doc - Infra manifest with outputs
+ * @param {Function} probe - probeHttps(baseUrl, path, label)
+ * @returns {Promise<void>}
+ */
+async function waitForApplications(doc, probe) {
+  await probe(doc.outputs.webAppUrl.value, '/api/v1/health/readiness', 'Miso');
+  const realmUrl = doc.outputs.keycloakRealmUrl.value;
+  if (typeof realmUrl !== 'string' || !realmUrl.startsWith('https://')) {
+    throw new Error('ARM output keycloakRealmUrl is not a valid HTTPS URL');
+  }
+  const parsed = new URL(realmUrl);
+  await probe(parsed.origin, parsed.pathname, 'Keycloak');
+}
+
+module.exports = { verifyRuntimeImagePull, waitForApplications };

package/lib/deployment/installation/docker-register.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * @fileoverview DOCKER `--stage register`: one idempotent Mori bootstrap request. The one-time
+ * Service API Key is written only to the local user secrets file (never the shared store or a
+ * remote secrets API) and then materialized into the ignored workspace `.env`.
+ */
+
+const { materializeWorkspace, saveInfra } = require('./workspace');
+const { missingRequiredFields } = require('./infra-manifest');
+const { MORI_SERVICE_KEY } = require('./infra-catalog');
+const { materializeWorkspaceSecrets } = require('./workspace-secrets');
+const { assertIgnoredSecretFile } = require('./workspace-files');
+
+const LOST_KEY_GUIDANCE =
+  `The one-time Mori installation key is not in local secrets (${MORI_SERVICE_KEY}). ` +
+  'Mori issues it only once, so Builder will not request another. Restore it with ' +
+  `"aifabrix secret set ${MORI_SERVICE_KEY} <value>" or ask the Mori administrator to rotate the installation key.`;
+
+function defaultDeps() {
+  const { bootstrapMarketplaceInstallation } = require('../../api/marketplace-bootstrap.api');
+  const { saveLocalSecret } = require('../../utils/local-secrets');
+  const { loadSecrets } = require('../../core/secrets');
+  return { bootstrap: bootstrapMarketplaceInstallation, saveLocalSecret, loadSecrets };
+}
+
+function setStatus(doc, value, evidence) {
+  doc.registration.status = { ...doc.registration.status, value };
+  if (evidence !== undefined) doc.registration.evidence = evidence;
+}
+
+async function hasLocalKey(deps) {
+  const secrets = (await deps.loadSecrets()) || {};
+  const value = secrets[MORI_SERVICE_KEY];
+  return typeof value === 'string' && value.trim() !== '' && !value.startsWith('kv://');
+}
+
+function bootstrapBody(doc) {
+  return {
+    subscriptionId: doc.subscriptionId.value,
+    tenantId: doc.tenantId.value,
+    resourceGroupName: doc.resourceGroup.value,
+    cloudVendor: 'DOCKER',
+    marketplaceSubscriptionId: doc.marketplaceSubscriptionId.value || ''
+  };
+}
+
+function evidenceFrom(data) {
+  return {
+    apiKeyId: data.apiKeyId || null,
+    keyPrefix: data.keyPrefix || null,
+    createdAt: data.createdAt || null,
+    installation: data.installation || null,
+    entitlement: data.entitlement || null
+  };
+}
+
+async function requestRegistration(workspace, doc, deps) {
+  setStatus(doc, 'requested');
+  saveInfra(workspace, doc);
+  const response = await deps.bootstrap(doc.moriBaseUrl.value.replace(/\/+$/, ''), bootstrapBody(doc));
+  if (!response || !response.success) {
+    const status = response?.status;
+    setStatus(doc, status === 409 ? 'conflict' : 'not-registered');
+    saveInfra(workspace, doc);
+    if (status === 409) throw new Error(`Mori reports this installation is already registered. ${LOST_KEY_GUIDANCE}`);
+    throw new Error(`Mori registration failed${status ? ` (HTTP ${status})` : ' (network error)'}; no key was issued. Rerun when Mori is reachable.`);
+  }
+  const data = response.data?.data || response.data || {};
+  if (typeof data.apiKey !== 'string' || data.apiKey === '') {
+    setStatus(doc, 'failed');
+    saveInfra(workspace, doc);
+    throw new Error('Mori registration returned no installation key; contact the Mori administrator before retrying');
+  }
+  await deps.saveLocalSecret(MORI_SERVICE_KEY, data.apiKey);
+  setStatus(doc, 'registered', evidenceFrom(data));
+  saveInfra(workspace, doc);
+}
+
+/**
+ * Runs DOCKER registration.
+ * @param {Object} workspace - Opened workspace
+ * @param {Object} input - Validated stage input
+ * @param {Object} [overrides] - Injected dependencies (bootstrap, saveLocalSecret, loadSecrets, secretsApi, templatePath)
+ * @returns {Promise<{ doc: Object, alreadyRegistered: boolean }>}
+ */
+async function runDockerRegisterStage(workspace, input, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  const { doc } = materializeWorkspace(workspace, input, overrides);
+  const missing = missingRequiredFields(doc);
+  if (missing.length > 0) {
+    throw new Error(`Set these fields in ${workspace.paths.infra}, then rerun:\n  - ${missing.join('\n  - ')}`);
+  }
+  assertIgnoredSecretFile(workspace.paths.env, workspace.root);
+  const status = doc.registration.status.value;
+  const alreadyRegistered = status === 'registered';
+  if (['registered', 'requested', 'conflict'].includes(status)) {
+    if (!(await hasLocalKey(deps))) throw new Error(LOST_KEY_GUIDANCE);
+    if (!alreadyRegistered) {
+      setStatus(doc, 'registered');
+      saveInfra(workspace, doc);
+    }
+  } else {
+    await requestRegistration(workspace, doc, deps);
+  }
+  await materializeWorkspaceSecrets({
+    vendor: 'DOCKER', envPath: workspace.paths.env, root: workspace.root, secretsApi: overrides.secretsApi
+  });
+  return { doc, alreadyRegistered };
+}
+
+module.exports = { runDockerRegisterStage, LOST_KEY_GUIDANCE };

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

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * @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.
+ */
+
+const { validateControllerUrl } = require('../../utils/deployment-validation');
+const { readWorkspaceEnv } = require('./workspace-env');
+const { materializeWorkspaceSecrets } = require('./workspace-secrets');
+
+/**
+ * Resolves the Controller URL for an environment stage and persists an explicit override.
+ * @param {Object} params - Inputs
+ * @param {Object} params.envDoc - Environment document (mutated on override)
+ * @param {Object} params.infra - Infra manifest
+ * @param {Object.<string,string>} params.env - Workspace .env values
+ * @param {string} [params.override] - Validated --controller-url
+ * @returns {string} Controller URL
+ */
+function resolveControllerUrl({ envDoc, infra, env, override }) {
+  if (override) {
+    envDoc.controllerUrl = { ...envDoc.controllerUrl, value: override, source: 'cli' };
+  }
+  const candidate = envDoc.controllerUrl.value || env.CONTROLLER_URL || infra.controllerUrl?.value;
+  if (!candidate) {
+    throw new Error('No Controller URL is recorded for this installation. Run --stage infra first or pass --controller-url https://<host>/miso.');
+  }
+  return validateControllerUrl(candidate).replace(/\/+$/, '');
+}
+
+async function workspaceApiKey(workspace, secretsApi) {
+  const existing = readWorkspaceEnv(workspace.paths.env).MISO_API_KEY;
+  if (existing) return existing;
+  const resolved = await materializeWorkspaceSecrets({
+    vendor: 'AZURE', envPath: workspace.paths.env, root: workspace.root, names: ['MISO_API_KEY'], secretsApi
+  });
+  return resolved.MISO_API_KEY;
+}
+
+/**
+ * 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 }>}
+ */
+async function resolveEnvironmentAuth({ 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' };
+  }
+  if (processEnv.MISO_API_KEY) {
+    return { 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' };
+  }
+  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' };
+  }
+  throw new Error(
+    `No Controller authentication for ${controllerUrl}. Run "aifabrix login -c ${controllerUrl}", ` +
+    'or set MISO_API_KEY (or --miso-api-key-env <NAME>) to a temporary installation key.'
+  );
+}
+
+module.exports = { resolveControllerUrl, resolveEnvironmentAuth };

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

@@ -0,0 +1,165 @@
+'use strict';
+
+/**
+ * @fileoverview `environment-dev|tst|pro.json` generation and the minimal Miso request
+ * projections (create, update, validate/deploy). Workspace metadata wrappers never reach Miso.
+ */
+
+// Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
+const fs = require('../../internal/fs-real-sync');
+const path = require('path');
+const yaml = require('js-yaml');
+const { normalizePreset } = require('../environment-config');
+
+const ENVIRONMENT_SCHEMA_VERSION = '2.0.0';
+const ENVIRONMENT_NAMES = Object.freeze({ dev: 'Development', tst: 'Test', pro: 'Production' });
+const APPLICATION_TEMPLATES = path.resolve(__dirname, '../../../templates/applications');
+const DEFAULT_APPLICATIONS = Object.freeze(['dataplane', 'builder-api']);
+
+function entry(value, source, description, extra = {}) {
+  return { value, source, description, ...extra };
+}
+
+function defaultSections(envKey) {
+  return {
+    environment: entry(envKey, 'stage', 'Logical environment owned by this file.'),
+    name: entry(ENVIRONMENT_NAMES[envKey], 'generated', 'Display name sent to Miso.'),
+    preset: entry('s', 'cliOrFile', 'Environment sizing preset.'),
+    controllerUrl: { value: null, valueFromEnv: 'CONTROLLER_URL', source: 'infraOutput', description: 'Activated Miso Controller URL; an explicit value overrides the workspace .env.' },
+    serviceName: { inheritFrom: 'installId', source: 'environment-infra.json', description: 'Service name used for resource naming.' },
+    location: { inheritFrom: 'parameters.location', source: 'environment-infra.json', description: 'Azure region for this environment.' },
+    subscriptionId: { inheritFrom: 'subscriptionId', source: 'environment-infra.json', description: 'Azure subscription for this environment.' },
+    resourceGroupName: entry(null, 'generated', 'Azure resource group for this environment; null uses "<resource-group>-<environment>-rg".'),
+    networking: entry({ enablePrivateNetworking: false, enableAzureDns: false }, 'generated', 'Explicit environment networking sent to Miso.'),
+    allowedIPs: entry([], 'user', 'Environment API allowed CIDRs; independent of infra allowMyIp.'),
+    infrastructureAccess: entry([], 'user', 'Explicit environment infrastructure access entries.'),
+    applications: entry([...DEFAULT_APPLICATIONS], 'templateDefault', 'Application set whose top-level required variables this environment must provide.'),
+    variables: {},
+    request: entry(null, 'projection', 'Last non-secret request projection sent to Miso.'),
+    deployment: {
+      status: entry('not-deployed', 'controller', 'Latest deployment status.'),
+      id: entry(null, 'controller', 'Controller deployment identifier after submission.'),
+      updatedAt: null,
+      error: null
+    }
+  };
+}
+
+/**
+ * Creates or normalizes an environment file, preserving user-owned values.
+ * @param {{ envKey: string, existing: Object|null }} params - Inputs
+ * @returns {Object} Environment document
+ */
+function buildEnvironmentDocument({ envKey, existing }) {
+  const current = existing || {};
+  if (existing && existing.schemaVersion !== ENVIRONMENT_SCHEMA_VERSION) {
+    throw new Error(`environment-${envKey}.json schemaVersion ${existing.schemaVersion} is not supported; expected ${ENVIRONMENT_SCHEMA_VERSION}`);
+  }
+  if (existing && existing.environment?.value !== envKey) {
+    throw new Error(`environment-${envKey}.json records environment "${existing.environment?.value}"`);
+  }
+  const defaults = defaultSections(envKey);
+  const doc = { schemaVersion: ENVIRONMENT_SCHEMA_VERSION };
+  for (const [key, value] of Object.entries(defaults)) {
+    doc[key] = key === 'environment' ? value : (current[key] || value);
+  }
+  return doc;
+}
+
+function inherited(doc, field, infra) {
+  const item = doc[field];
+  if (item.value !== undefined && item.value !== null && item.value !== '') return item.value;
+  return String(item.inheritFrom).split('.').reduce((node, key) => node?.[key], infra)?.value;
+}
+
+/**
+ * Builds the explicit Miso placement for an environment from workspace files only.
+ * @param {Object} doc - Environment document
+ * @param {Object} infra - Infra manifest
+ * @returns {Object} Placement values
+ */
+function buildPlacement(doc, infra) {
+  const envKey = doc.environment.value;
+  return {
+    key: envKey,
+    environment: envKey,
+    preset: normalizePreset(doc.preset.value),
+    serviceName: inherited(doc, 'serviceName', infra),
+    location: inherited(doc, 'location', infra),
+    resourceGroupName: doc.resourceGroupName.value || `${infra.resourceGroup.value}-${envKey}-rg`,
+    subscriptionId: inherited(doc, 'subscriptionId', infra)
+  };
+}
+
+/**
+ * @param {Object} doc - Environment document
+ * @param {Object} infra - Infra manifest
+ * @returns {{ create: Object, update: Object, deploy: Object }} Request bodies
+ */
+function buildMisoRequests(doc, infra) {
+  const placement = buildPlacement(doc, infra);
+  const { key, environment, ...configuration } = placement;
+  const explicit = {
+    networking: doc.networking.value,
+    allowedIPs: doc.allowedIPs.value,
+    infrastructureAccess: doc.infrastructureAccess.value
+  };
+  return {
+    create: { key, name: doc.name.value, environment, configuration: { ...configuration, ...explicit } },
+    update: { name: doc.name.value, configuration: { ...configuration, ...explicit } },
+    deploy: { environmentConfig: placement }
+  };
+}
+
+function readApplicationContract(appKey, templatesDir) {
+  const dir = path.join(templatesDir, appKey);
+  const manifestPath = path.join(dir, 'application.yaml');
+  if (!/^[a-z0-9-]+$/.test(appKey) || !fs.existsSync(manifestPath)) {
+    throw new Error(`Application "${appKey}" listed in the environment file has no application template`);
+  }
+  const manifest = yaml.load(fs.readFileSync(manifestPath, 'utf8')) || {};
+  const envTemplatePath = path.join(dir, 'env.template');
+  const declared = new Set();
+  if (fs.existsSync(envTemplatePath)) {
+    for (const line of fs.readFileSync(envTemplatePath, 'utf8').split(/\r?\n/)) {
+      const match = line.match(/^\s*([A-Z_][A-Z0-9_]*)=/);
+      if (match) declared.add(match[1]);
+    }
+  }
+  for (const item of manifest.configuration || []) if (item && item.name) declared.add(item.name);
+  return { required: Array.isArray(manifest.required) ? manifest.required : [], declared };
+}
+
+/**
+ * Rebuilds the application-required variable catalog with redacted resolution state.
+ * @param {Object} doc - Environment document (mutated)
+ * @param {Object.<string,string>} values - Workspace .env plus explicit process values
+ * @param {string} [templatesDir] - Application templates directory
+ * @returns {string[]} Unresolved or undeclared problems
+ */
+function refreshVariableCatalog(doc, values, templatesDir = APPLICATION_TEMPLATES) {
+  const variables = {};
+  const problems = [];
+  for (const appKey of doc.applications.value) {
+    const contract = readApplicationContract(appKey, templatesDir);
+    for (const name of contract.required) {
+      if (!contract.declared.has(name)) problems.push(`${appKey} requires ${name}, which its env/configuration contract does not declare`);
+      const item = variables[name] || { valueFromEnv: name, requiredBy: [], source: 'secretEnv', description: `Required by the selected application set for ${doc.environment.value}.` };
+      item.requiredBy = [...new Set([...item.requiredBy, appKey])].sort();
+      variables[name] = item;
+    }
+  }
+  for (const [name, item] of Object.entries(variables)) {
+    item.resolution = values[name] ? 'resolved' : 'missing';
+    if (!values[name]) problems.push(`${name} (required by ${item.requiredBy.join(', ')}) is not set in the workspace .env or process environment`);
+  }
+  doc.variables = Object.fromEntries(Object.keys(variables).sort().map(name => [name, variables[name]]));
+  return problems;
+}
+
+module.exports = {
+  ENVIRONMENT_SCHEMA_VERSION,
+  buildEnvironmentDocument,
+  buildMisoRequests,
+  refreshVariableCatalog
+};