@aifabrix/builder 2.56.0 → 2.57.0

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

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE infra readiness evidence: both web app identities hold AcrPull on the
+ * workspace registry with managed-identity image pull enabled, and Miso and Keycloak answer over
+ * HTTPS. Local `az acr login` success is never treated as readiness.
+ */
+
+const APP_OUTPUTS = Object.freeze([
+  { name: 'webAppName', label: 'Miso' },
+  { name: 'keycloakWebAppName', label: 'Keycloak' }
+]);
+
+function scoped(args, doc) {
+  return [...args, '--subscription', doc.subscriptionId.value];
+}
+
+function verifyAppImagePull(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`);
+  }
+}
+
+/**
+ * Verifies persistent managed-identity image-pull authorization for both web apps.
+ * @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
+};

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

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE `--stage dev|tst|pro`: server-reported activation check, then Miso
+ * create-or-update, validate, deploy (resuming an active deployment on 409) and poll to a terminal
+ * state. Makes no Mori, license, token-issuance or Azure calls.
+ */
+
+const { maskSensitiveData } = require('../../utils/log-redaction');
+const { normalizePreset } = require('../environment-config');
+const { readJsonIfExists, environmentFileName } = require('./workspace-files');
+const { saveInfra, saveEnvironment } = require('./workspace');
+const { buildEnvironmentDocument, buildMisoRequests, refreshVariableCatalog } = require('./environment-manifest');
+const { readWorkspaceEnv, removeWorkspaceEnvKey } = require('./workspace-env');
+const { resolveControllerUrl, resolveEnvironmentAuth } = require('./environment-auth');
+
+const FAILED_STATES = Object.freeze(['failed', 'error', 'cancelled']);
+
+function defaultApi() {
+  const environments = require('../../api/environments.api');
+  const deployments = require('../../api/deployments.api');
+  return { ...environments, deployEnvironment: deployments.deployEnvironment, getDeployment: deployments.getDeployment };
+}
+
+function payload(response) {
+  const body = response?.data;
+  return body && typeof body === 'object' && body.data !== undefined ? body.data : body;
+}
+
+function apiFailure(step, response) {
+  const detail = maskSensitiveData(String(response?.formattedError || response?.error || 'request failed'));
+  const error = new Error(`Miso ${step} failed${response?.status ? ` (HTTP ${response.status})` : ''}: ${detail}`);
+  error.status = response?.status;
+  return error;
+}
+
+async function assertTenantActive(ctx) {
+  const response = await ctx.api.getTenantStatus(ctx.controllerUrl, ctx.auth);
+  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';
+  ctx.infra.tenantActivation.status = { ...ctx.infra.tenantActivation.status, value: recorded, checkedAt: ctx.now().toISOString() };
+  saveInfra(ctx.workspace, ctx.infra);
+  if (status !== 'ACTIVE') {
+    const url = ctx.infra.tenantActivation.url?.value || ctx.controllerUrl;
+    throw new Error(`Tenant activation is ${status}. Open ${url}, sign in and complete activation, then rerun this stage.`);
+  }
+}
+
+function needsUpdate(current, update) {
+  const existing = current?.configuration || {};
+  return Object.entries(update.configuration).some(([key, value]) => JSON.stringify(existing[key]) !== JSON.stringify(value)) ||
+    (update.name && current?.name !== update.name);
+}
+
+async function updateExisting(ctx, current, requests) {
+  if (current?.environment && current.environment !== ctx.envKey) {
+    throw new Error(`Controller environment ${ctx.envKey} has environment type "${current.environment}"; refusing to change it`);
+  }
+  if (!needsUpdate(current, requests.update)) return 'unchanged';
+  const patched = await ctx.api.updateEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth, requests.update);
+  if (!patched.success) throw apiFailure('environment update', patched);
+  return 'updated';
+}
+
+async function createOrUpdate(ctx, requests) {
+  const found = await ctx.api.getEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth);
+  if (found.success) return updateExisting(ctx, payload(found), requests);
+  if (found.status !== 404) throw apiFailure('environment read', found);
+  const created = await ctx.api.createEnvironment(ctx.controllerUrl, ctx.auth, requests.create);
+  if (created.success) return 'created';
+  if (created.status !== 409) throw apiFailure('environment create', created);
+  const reread = await ctx.api.getEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth);
+  if (!reread.success) throw apiFailure('environment read', reread);
+  return updateExisting(ctx, payload(reread), requests);
+}
+
+async function validateRequest(ctx, request) {
+  const response = await ctx.api.validateEnvironmentDeployment(ctx.controllerUrl, ctx.envKey, ctx.auth, request);
+  if (!response.success) throw apiFailure('environment validation', response);
+  const result = payload(response) || {};
+  if (result.valid !== true) {
+    const errors = (result.errors || []).map(item => maskSensitiveData(typeof item === 'string' ? item : JSON.stringify(item)));
+    throw new Error(`Miso rejected the environment configuration:\n  - ${errors.join('\n  - ') || 'no details returned'}`);
+  }
+}
+
+async function submitDeployment(ctx, request) {
+  const response = await ctx.api.deployEnvironment(ctx.controllerUrl, ctx.envKey, ctx.auth, { ...request, dryRun: false });
+  if (response.success) {
+    const data = payload(response) || {};
+    return { deploymentId: data.deploymentId || data.id, resumed: false };
+  }
+  const activeId = response.errorData?.deploymentId || response.errorData?.extensions?.deploymentId;
+  if (response.status === 409 && activeId) return { deploymentId: activeId, resumed: true };
+  throw apiFailure('environment deploy', response);
+}
+
+async function pollDeployment(ctx, deploymentId) {
+  for (let attempt = 1; attempt <= ctx.maxAttempts; attempt++) {
+    const response = await ctx.api.getDeployment(ctx.controllerUrl, ctx.envKey, deploymentId, ctx.auth);
+    if (!response.success && response.status !== 404) throw apiFailure('deployment status', response);
+    const status = String(payload(response)?.status || 'pending').toLowerCase();
+    if (status === 'completed') return { status };
+    if (FAILED_STATES.includes(status)) {
+      return { status, error: maskSensitiveData(String(payload(response)?.message || payload(response)?.error || status)) };
+    }
+    await ctx.sleep(ctx.pollInterval);
+  }
+  return { status: 'timeout', error: `No terminal state after ${ctx.maxAttempts} checks` };
+}
+
+function recordDeployment(ctx, envDoc, state) {
+  envDoc.deployment = {
+    ...envDoc.deployment,
+    status: { ...envDoc.deployment.status, value: state.status },
+    id: { ...envDoc.deployment.id, value: state.deploymentId ?? envDoc.deployment.id.value },
+    updatedAt: ctx.now().toISOString(),
+    error: state.error || null
+  };
+  saveEnvironment(ctx.workspace, ctx.envKey, envDoc);
+}
+
+function prepareEnvironmentDocument(ctx, input, env) {
+  const envDoc = buildEnvironmentDocument({ envKey: ctx.envKey, existing: readJsonIfExists(ctx.envFile) });
+  if (input.preset !== undefined) envDoc.preset = { ...envDoc.preset, value: normalizePreset(input.preset), source: 'cli' };
+  const problems = refreshVariableCatalog(envDoc, { ...env, ...ctx.processEnv }, ctx.templatesDir);
+  const requests = buildMisoRequests(envDoc, ctx.infra);
+  envDoc.request = { ...envDoc.request, value: requests.deploy };
+  saveEnvironment(ctx.workspace, ctx.envKey, envDoc);
+  if (problems.length > 0) throw new Error(`Environment ${ctx.envKey} is missing required variables:\n  - ${problems.join('\n  - ')}`);
+  return { envDoc, requests };
+}
+
+function assertInfraReady(workspace, envKey) {
+  const infra = workspace.infra;
+  if (!infra || infra.vendor?.value !== 'AZURE' || infra.deployment?.status?.value !== 'succeeded' || !infra.controllerUrl?.value) {
+    throw new Error(`Shared infrastructure is not deployed for this workspace. Run "af env deploy ${workspace.infra?.resourceGroup?.value || '<resource-group>'} --stage infra" before --stage ${envKey}.`);
+  }
+  return infra;
+}
+
+function buildContext(workspace, input, deps) {
+  const envKey = input.stage;
+  return {
+    workspace, envKey,
+    infra: assertInfraReady(workspace, envKey),
+    envFile: workspace.paths.environment(envKey),
+    api: deps.api || defaultApi(),
+    now: deps.now || (() => new Date()),
+    sleep: deps.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms))),
+    pollInterval: deps.pollInterval ?? 5000,
+    maxAttempts: deps.maxAttempts ?? 360,
+    processEnv: deps.env || process.env,
+    templatesDir: deps.templatesDir
+  };
+}
+
+/**
+ * Runs a dev, tst or pro environment stage.
+ * @param {Object} workspace - Opened workspace
+ * @param {Object} input - Validated stage input
+ * @param {Object} [deps] - Injected api, getDeviceToken, secretsApi, env, now, sleep, pollInterval, maxAttempts, templatesDir
+ * @returns {Promise<{ envKey: string, deploymentId: string, status: string, change: string, resumed: boolean }>}
+ */
+async function runEnvironmentStage(workspace, input, deps = {}) {
+  const ctx = buildContext(workspace, input, deps);
+  const env = readWorkspaceEnv(workspace.paths.env);
+  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 }
+  });
+  ctx.auth = authConfig;
+  await assertTenantActive(ctx);
+  const change = await createOrUpdate(ctx, requests);
+  await validateRequest(ctx, requests.deploy);
+  const { deploymentId, resumed } = await submitDeployment(ctx, requests.deploy);
+  if (!deploymentId) throw new Error('Miso accepted the deployment without a deploymentId');
+  recordDeployment(ctx, envDoc, { status: 'running', deploymentId });
+  const final = await pollDeployment(ctx, deploymentId);
+  recordDeployment(ctx, envDoc, { ...final, deploymentId });
+  if (final.status !== 'completed') {
+    throw new Error(`Environment ${ctx.envKey} deployment ${deploymentId} ended as ${final.status}: ${final.error}. Rerun the stage to resume.`);
+  }
+  if (source === 'workspace') removeWorkspaceEnvKey(workspace.paths.env, 'MISO_API_KEY');
+  return { envKey: ctx.envKey, deploymentId, status: final.status, change, resumed, fileName: environmentFileName(ctx.envKey) };
+}
+
+module.exports = { runEnvironmentStage };

package/lib/deployment/installation/index.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * @fileoverview Resource-group installation workspace dispatcher for
+ * `env deploy <resource-group> --stage register|infra|dev|tst|pro`.
+ * All input validation happens before any filesystem, network or cloud mutation.
+ */
+
+const { resolveStageInput, validateResourceGroupKey, ENVIRONMENT_STAGES } = require('./stage-input');
+const { openWorkspace } = require('./workspace');
+
+/**
+ * Runs one installation workspace stage.
+ * @param {string} resourceGroupKey - Positional resource-group key
+ * @param {Object} options - Commander options
+ * @param {Object} [deps] - Injected dependencies for stage runners
+ * @returns {Promise<Object>} Stage result with `stage`, `vendor` and `workspaceDir`
+ */
+async function deployInstallationStage(resourceGroupKey, options, deps = {}) {
+  const resourceGroup = validateResourceGroupKey(resourceGroupKey);
+  const workspace = openWorkspace(resourceGroup, { root: deps.root });
+  const input = resolveStageInput(resourceGroup, options, workspace.infra?.vendor?.value);
+  const base = { stage: input.stage, vendor: input.vendor, workspaceDir: workspace.dir };
+  if (input.stage === 'register') {
+    const { runDockerRegisterStage } = require('./docker-register');
+    return { ...base, ...(await runDockerRegisterStage(workspace, input, deps)) };
+  }
+  if (input.stage === 'infra') {
+    const { runAzureInfraStage } = require('./azure-infra-stage');
+    return { ...base, ...(await runAzureInfraStage(workspace, input, deps)) };
+  }
+  if (ENVIRONMENT_STAGES.includes(input.stage)) {
+    const { runEnvironmentStage } = require('./environment-stage');
+    return { ...base, ...(await runEnvironmentStage(workspace, input, deps)) };
+  }
+  throw new Error(`Unsupported stage ${input.stage}`);
+}
+
+module.exports = { deployInstallationStage };