@aifabrix/builder 2.60.0 → 2.62.0

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

@@ -18,7 +18,10 @@ const ENV_VAR_NAME = /^[A-Z_][A-Z0-9_]*$/;
 const LEGACY_MARKETPLACE_FLAGS = Object.freeze([
   'marketplaceJson', 'parameters', 'subscription', 'resourceGroup', 'installId'
 ]);
-const DOCKER_SETUP_GUIDANCE = 'DOCKER installations deploy through "aifabrix setup"; only --stage register is supported for DOCKER.';
+const DOCKER_SETUP_GUIDANCE =
+  'Install a DOCKER platform with "aifabrix setup", and deploy its environments with ' +
+  '"aifabrix env deploy local --stage <env>". Only --stage register is supported for a ' +
+  'DOCKER vendor on a non-local installation.';
 
 /**
  * True when options select the deprecated explicit Marketplace/journal mode.
@@ -174,6 +177,7 @@ function resolveStageInput(resourceGroupKey, options, persistedVendor) {
 module.exports = {
   WORKSPACE_STAGES,
   ENVIRONMENT_STAGES,
+  validateStage,
   VENDORS,
   DEFAULT_VENDOR,
   isLegacyMarketplaceMode,

package/lib/generator/builders.js

@@ -343,6 +343,9 @@ function addValidatedConfigSections(deployment, variables) {
  * @param {Object} variables - Variables configuration
  */
 function addSimpleOptionalFields(deployment, variables) {
+  if (variables.webSocketsEnabled !== undefined) {
+    deployment.webSocketsEnabled = variables.webSocketsEnabled;
+  }
   if (variables.startupCommand) {
     deployment.startupCommand = variables.startupCommand;
   }
@@ -419,4 +422,3 @@ module.exports = {
   sanitizeAuthType,
   validateBuildFields
 };
-

package/lib/generator/index.js

@@ -22,6 +22,7 @@ const { generateControllerManifest } = require('./external-controller-manifest')
 const { resolveVersionForApp } = require('../utils/image-version');
 const { getContainerPort } = require('../utils/port-resolver');
 const { buildEnvVarMap } = require('../utils/env-map');
+const { mergeAdditionalPublishedPorts } = require('../utils/docker-manifest-public-port');
 
 /**
  * Generates deployment JSON from application configuration files
@@ -247,6 +248,7 @@ async function buildDeploymentManifestInMemory(appName, options = {}) {
       ? parseInt(deployment.port, 10) : (typeof deployment.port === 'number' ? deployment.port : effectivePort);
   }
   const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
+  await mergeAdditionalPublishedPorts(envVarMap, variablesWithVersion);
   substituteEnvVarsInDeployment(deployment, envVarMap);
   _validator.validateNoUnresolvedVariablesInDeployment(deployment);
   return { deployment, appPath };
@@ -300,6 +302,7 @@ async function writeRegularDeployJson(appName, appPath, appType, options = {}) {
   };
   const effectivePort = getEffectivePortForSubstitution(variablesWithVersion, 3000);
   const envVarMap = await buildEnvVarMap('docker', null, null, { appPort: effectivePort });
+  await mergeAdditionalPublishedPorts(envVarMap, variablesWithVersion);
   const deployment = buildAndValidateDeployment(appName, variablesWithVersion, envTemplate, rbac, {
     envVarMap,
     target: options.target

package/lib/generator/split-variables.js

@@ -46,7 +46,7 @@ function extractRequirementsSection(deployment) {
 }
 
 function extractOptionalSection(deployment, sectionName, optional) {
-  if (!deployment[sectionName]) return;
+  if (!deployment[sectionName] && !(sectionName === 'webSocketsEnabled' && deployment[sectionName] === false)) return;
   optional[sectionName] = sectionName === 'authentication'
     ? { ...deployment[sectionName] }
     : deployment[sectionName];
@@ -57,7 +57,7 @@ function extractOptionalSections(deployment) {
   const names = [
     'healthCheck', 'authentication', 'build', 'repository', 'deployment',
     'startupCommand', 'runtimeVersion', 'scaling', 'frontDoorRouting',
-    'environmentScopedResources', 'required'
+    'environmentScopedResources', 'required', 'webSocketsEnabled'
   ];
   for (const sectionName of names) {
     extractOptionalSection(deployment, sectionName, optional);

package/lib/lifecycle/product-model.js

@@ -134,6 +134,7 @@ function computeOperationalReadinessPercent(checks) {
   let earned = 0;
   let total = 0;
   for (const [key, weight] of Object.entries(OPERATIONS_WEIGHTS)) {
+    if (checks[key] === null) continue;
     total += weight;
     if (checks[key] === true) {
       earned += weight;
@@ -159,9 +160,9 @@ function buildOperationsChecksFromSteps(steps) {
     authorization: integration || e2e,
     openApi: validation,
     mappings: validation,
-    sync: e2e,
-    crud: e2e,
-    execution: e2e,
+    sync: steps.keyedDocumentGet === true ? null : e2e,
+    crud: steps.keyedDocumentGet === true ? steps.documentPersistence === true : e2e,
+    execution: steps.keyedDocumentGet === true ? steps.documentPersistence === true : e2e,
     validation,
     unitTests: unit,
     integrationTests: integration,

package/lib/lifecycle/report-display.js

@@ -132,8 +132,9 @@ function displayOperationsVerificationSteps(detailsGrouped) {
   for (const [groupName, keys] of groups) {
     logger.log(chalk.white(groupName));
     for (const key of keys) {
-      const passed = detailsGrouped[groupName.toLowerCase()]?.[key] ?? detailsGrouped[key];
-      const glyph = passed ? successGlyph() : failureGlyph();
+      const group = detailsGrouped[groupName.toLowerCase()];
+      const passed = group && Object.hasOwn(group, key) ? group[key] : detailsGrouped[key];
+      const glyph = passed === null ? chalk.gray('⏭ Not applicable') : passed ? successGlyph() : failureGlyph();
       logger.log(`  ${labels[key] || key}`.padEnd(24) + glyph);
     }
   }

package/lib/parameters/database-adoption.js

@@ -0,0 +1,125 @@
+/**
+ * Adopting the databases an existing installation already has (plan 210.0, Miso 227.3).
+ *
+ * Before environments were encoded in the name, a local install created `keycloak`, `miso`
+ * and `dataplane` flat. Encoding the environment renames every one of them, and a rename on
+ * a live Postgres means dropping and recreating — which means losing the data. 227.3 required
+ * the same thing for Azure and answered it the same way: **adopt the database under the name
+ * it already has** rather than move it.
+ *
+ * Miso keeps old names resolvable (`legacyVaultSecretNames`) and adopts a bare legacy
+ * database in `physical-database-adoption.ts`. This is that rule, locally.
+ *
+ * ## The one thing adoption must never do
+ *
+ * Only the environment the legacy install *was* may adopt its databases. A local install
+ * before this plan was `dev` and nothing else, so `dev` adopting `dataplane` continues what
+ * was already running. **`pro` adopting `dataplane` would point production at the database a
+ * developer has been working in** — the exact collision environment-encoded names exist to
+ * prevent, arriving through the mechanism meant to prevent it. So adoption is refused for
+ * every environment except the legacy one, and a fresh install adopts nothing because there
+ * is nothing to adopt.
+ *
+ * Pure: no I/O. The caller supplies the names the server already has.
+ *
+ * @fileoverview Adopt existing unprefixed databases instead of renaming them
+ */
+
+'use strict';
+
+const { resolvePhysicalDatabaseNames } = require('./physical-database-naming');
+
+/**
+ * The environment a pre-environment installation implicitly was.
+ *
+ * Everything an older local install created belongs to `dev`: there was no other environment
+ * to have created it.
+ */
+const LEGACY_ENVIRONMENT = 'dev';
+
+/** How a name was arrived at. */
+const NAME_ORIGIN = Object.freeze({ CONTRACT: 'contract', ADOPTED: 'adopted' });
+
+/**
+ * The role that owns a database, derived the way the server already derived it.
+ *
+ * An adopted database keeps its existing role, and that role was built from the database name
+ * with hyphens flattened. Re-deriving it the same way is what makes adoption a no-op rather
+ * than a second role on an existing database.
+ *
+ * @param {string} databaseName - Physical database name
+ * @returns {string}
+ */
+function roleNameForDatabase(databaseName) {
+  return `${String(databaseName).replace(/-/g, '_')}_user`;
+}
+
+/**
+ * Whether this environment may adopt a legacy database.
+ *
+ * @param {string} environment - Environment key
+ * @returns {boolean}
+ */
+function canAdoptInEnvironment(environment) {
+  return String(environment ?? '').trim().toLowerCase() === LEGACY_ENVIRONMENT;
+}
+
+/**
+ * Resolve the names to use for one database, adopting an existing one where that applies.
+ *
+ * @param {Object} params - Inputs
+ * @param {string} params.logicalName - Logical database name from the manifest
+ * @param {string} params.appKey - Owning application key
+ * @param {string} params.environment - Environment key
+ * @param {Iterable<string>} [params.existingDatabaseNames] - Databases the server already has
+ * @returns {{ logicalName: string, databaseName: string, roleName: string, origin: string }}
+ */
+function resolveDatabaseNamesWithAdoption(params = {}) {
+  const contract = resolvePhysicalDatabaseNames({
+    logicalName: params.logicalName,
+    appKey: params.appKey,
+    environment: params.environment
+  });
+  const existing = new Set(params.existingDatabaseNames || []);
+
+  // The contract name already being there is the normal case after the first run: adopting it
+  // and resolving it are the same answer, so this is reported as `contract` rather than as an
+  // adoption of something this plan created itself.
+  if (existing.has(contract.databaseName) || !canAdoptInEnvironment(params.environment)) {
+    return { ...stripSecretKey(contract), origin: NAME_ORIGIN.CONTRACT };
+  }
+
+  const legacyName = String(params.logicalName ?? '').trim();
+  if (!legacyName || !existing.has(legacyName)) {
+    return { ...stripSecretKey(contract), origin: NAME_ORIGIN.CONTRACT };
+  }
+  return {
+    logicalName: contract.logicalName,
+    databaseName: legacyName,
+    roleName: roleNameForDatabase(legacyName),
+    origin: NAME_ORIGIN.ADOPTED
+  };
+}
+
+/**
+ * `passwordSecretKey` is deliberately not carried forward: which grammar names that secret is
+ * Miso's, and the catalog key is what every consumer reads.
+ *
+ * @param {Object} names - From resolvePhysicalDatabaseNames
+ * @returns {{ logicalName: string, databaseName: string, roleName: string }}
+ */
+function stripSecretKey(names) {
+  return {
+    logicalName: names.logicalName,
+    databaseName: names.databaseName,
+    roleName: names.roleName
+  };
+}
+
+module.exports = {
+  LEGACY_ENVIRONMENT,
+  NAME_ORIGIN,
+  roleNameForDatabase,
+  canAdoptInEnvironment,
+  resolveDatabaseNamesWithAdoption
+};

package/lib/parameters/infra-parameter-catalog.js

@@ -135,7 +135,7 @@ function createCatalogApi(doc, exact, patterns) {
     const entry = findEntryForKey(key);
     const gen = entry && entry.generator;
     // emptyAllowed: e.g. Redis password when no requirepass.
-    // emptyString: optional user-supplied keys (OpenAI / Azure OpenAI) — absent resolves like ''.
+    // emptyString: optional user-supplied catalog keys — absent resolves like ''.
     return Boolean(gen && (gen.type === 'emptyAllowed' || gen.type === 'emptyString'));
   }
 

package/lib/parameters/physical-database-naming.js

@@ -0,0 +1,136 @@
+/**
+ * Physical database, role and password-secret names for a local installation.
+ *
+ * Local runs every entitled environment on one PostgreSQL server, which is 227.0's shared
+ * model. Without an environment segment two environments declaring the same logical
+ * database name collide on the database, the role and the secret — the defect Miso 227.3
+ * fixed for Azure. The local path had none of it: keys are derived as
+ * `databases-{appKey}-{i}-*` with no environment in them.
+ *
+ * This mirrors Miso's `resolvePhysicalDatabaseNames`
+ * (`services/infra-parameters/physical-database-naming.ts`) deliberately. Matching it makes
+ * a local environment and an Azure environment the same object at a different address,
+ * which is the point of validating a near-Azure stack in Docker. A second scheme would be
+ * two isolation rules to keep in step, and the Azure one already ships.
+ *
+ * Pure: no I/O. The environment comes from the caller, never from `process.env` and never
+ * from a manifest.
+ *
+ * @fileoverview Environment-encoded PostgreSQL naming for shared local infrastructure
+ */
+
+'use strict';
+
+/** Canonical environment keys. Matches the Azure and database vocabulary, not licence slots. */
+const PHYSICAL_NAME_ENVIRONMENTS = Object.freeze(['miso', 'dev', 'tst', 'pro']);
+
+/** PostgreSQL truncates identifiers at 63 bytes, silently, which would reintroduce collisions. */
+const POSTGRES_IDENTIFIER_LIMIT = 63;
+
+class UnknownPhysicalEnvironmentError extends Error {
+  constructor(environment) {
+    super(
+      `Unknown environment '${environment}'. Expected one of: ${PHYSICAL_NAME_ENVIRONMENTS.join(', ')}.`
+    );
+    this.name = 'UnknownPhysicalEnvironmentError';
+    this.environment = environment;
+  }
+}
+
+class PhysicalNameTooLongError extends Error {
+  constructor(resolvedName, limit) {
+    super(
+      `Resolved physical name '${resolvedName}' is ${resolvedName.length} characters, over the ` +
+      `${limit} character limit. Shorten the application key or the logical database name.`
+    );
+    this.name = 'PhysicalNameTooLongError';
+    this.resolvedName = resolvedName;
+    this.limit = limit;
+  }
+}
+
+/**
+ * Normalise a segment to the PostgreSQL identifier character set.
+ *
+ * @param {string} value - Raw segment
+ * @returns {string}
+ */
+function normalizeSegment(value) {
+  return String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+}
+
+/**
+ * Reject an unknown environment instead of defaulting to one.
+ *
+ * Defaulting is how a production database ends up on a development server, so this fails
+ * closed.
+ *
+ * @param {string} environment - Environment key
+ * @returns {string} Normalised environment key
+ * @throws {UnknownPhysicalEnvironmentError}
+ */
+function assertPhysicalEnvironment(environment) {
+  const normalized = String(environment ?? '').trim().toLowerCase();
+  if (!PHYSICAL_NAME_ENVIRONMENTS.includes(normalized)) {
+    throw new UnknownPhysicalEnvironmentError(environment);
+  }
+  return normalized;
+}
+
+/**
+ * Resolve the database, role and password-secret names together.
+ *
+ * Resolved as one call so a caller cannot take two of the three and leave the third
+ * verbatim, which is the shape of the original defect.
+ *
+ * @param {Object} params - Inputs
+ * @param {string} params.logicalName - Logical database name from the manifest
+ * @param {string} params.appKey - Application key
+ * @param {string} params.environment - Logical environment
+ * @returns {{ logicalName: string, databaseName: string, roleName: string, passwordSecretKey: string }}
+ * @throws {UnknownPhysicalEnvironmentError|PhysicalNameTooLongError|Error}
+ */
+function resolvePhysicalDatabaseNames(params = {}) {
+  const environment = assertPhysicalEnvironment(params.environment);
+  const logicalName = String(params.logicalName ?? '').trim();
+  const app = normalizeSegment(params.appKey);
+  const logical = normalizeSegment(logicalName);
+
+  if (!app) {
+    throw new Error('appKey is required to resolve a physical database name');
+  }
+  if (!logical) {
+    throw new Error('logicalName is required to resolve a physical database name');
+  }
+
+  const databaseName = `${environment}_${app}_${logical}`;
+  const roleName = `${databaseName}_user`;
+
+  // The role is the longest derived identifier, so checking it covers the database too.
+  if (roleName.length > POSTGRES_IDENTIFIER_LIMIT) {
+    throw new PhysicalNameTooLongError(roleName, POSTGRES_IDENTIFIER_LIMIT);
+  }
+
+  return {
+    logicalName,
+    databaseName,
+    roleName,
+    // Hyphenated because the vault naming contract rejects underscores.
+    passwordSecretKey: `${databaseName.replace(/_/g, '-')}-password`
+  };
+}
+
+module.exports = {
+  PHYSICAL_NAME_ENVIRONMENTS,
+  POSTGRES_IDENTIFIER_LIMIT,
+  UnknownPhysicalEnvironmentError,
+  PhysicalNameTooLongError,
+  normalizeSegment,
+  assertPhysicalEnvironment,
+  resolvePhysicalDatabaseNames
+};

package/lib/parameters/physical-secret-name.js

@@ -0,0 +1,194 @@
+/**
+ * The physical secret name for a catalog key (plan 210.0, mirroring Miso 227.4).
+ *
+ * Builder resolved `tst` and `pro` secrets by prefixing the logical key: `pro-<key>`. That is
+ * right for an environment-scoped parameter and **wrong for the other two cases**, which
+ * Miso's naming rule (`services/parameters/parameter-naming.ts`) states as:
+ *
+ * ```text
+ * system                          <key>            no prefix, deliberately
+ * environment-scoped              dev-<key>
+ * application-scoped              dev-<app>-<key>
+ * ```
+ *
+ * So the database password an installation actually holds is
+ * `pro-dataplane-databases-0-passwordKeyVault`, not `pro-databases-dataplane-0-passwordKeyVault`
+ * — the application segment sits before the key, not after the environment alone. And system
+ * names such as `keycloak-*` and `acr-*` must not move at all, because the Marketplace
+ * template writes them and every installation-level reader expects them where they are.
+ *
+ * Rather than restate that rule, this resolves the name the way Miso's `computeVaultSecretName`
+ * does: from the catalog entry's own `azure.vaultSecretName` or `azure.vaultSecretNamePattern`.
+ * The catalog is the Miso master and Builder mirrors it byte for byte, so the pattern is the
+ * contract. A key with no pattern is installation-wide by declaration, not by omission.
+ *
+ * This is why no caller may build a prefix itself: the three cases are not distinguishable
+ * from the key alone.
+ *
+ * @fileoverview Catalog-driven physical secret names, mirroring Miso's computeVaultSecretName
+ */
+
+'use strict';
+
+/** Database catalog keys carry both the owning application and the index in the key. */
+const DATABASE_KEY_PARTS = /^databases-([a-z0-9-]+)-(\d+)-(?:url|password)KeyVault$/;
+
+/**
+ * @param {string} key - Logical catalog key
+ * @returns {string} The index, or empty when the key is not a database key
+ */
+function extractDatabaseIndex(key) {
+  const match = String(key ?? '').match(DATABASE_KEY_PARTS);
+  return match ? match[2] : '';
+}
+
+/**
+ * The application a database key belongs to.
+ *
+ * Most database entries match the catalog's generic `keyPattern` rather than an exact key, so
+ * they carry no `ownerAppKey` to read — the owner is in the key. Without this the `{appKey}`
+ * placeholder resolves empty and the name collapses to `pro--databases-0-…`, a name nothing
+ * writes and nothing reads.
+ *
+ * @param {string} key - Logical catalog key
+ * @returns {string} The application key, or empty when the key is not a database key
+ */
+function extractDatabaseAppKey(key) {
+  const match = String(key ?? '').match(DATABASE_KEY_PARTS);
+  return match ? match[1] : '';
+}
+
+/**
+ * Substitute the placeholders a vault name pattern may carry.
+ *
+ * @param {string} pattern - From `azure.vaultSecretNamePattern`
+ * @param {string} key - Logical catalog key
+ * @param {{ environment?: string, serviceName?: string, appKey?: string }} context
+ * @returns {string}
+ */
+function applyVaultNamePattern(pattern, key, context = {}) {
+  return String(pattern)
+    .replace(/\{key\}/g, key)
+    .replace(/\{environment\}/g, context.environment ?? '')
+    .replace(/\{serviceName\}/g, context.serviceName ?? '')
+    .replace(/\{appKey\}/g, context.appKey ?? '')
+    .replace(/\{index\}/g, extractDatabaseIndex(key));
+}
+
+/**
+ * The physical name of the secret holding a logical key's value.
+ *
+ * @param {string} key - Logical catalog key
+ * @param {Object} [context] - Resolution context
+ * @param {string} [context.environment] - Environment key
+ * @param {string} [context.serviceName] - Installation service name
+ * @param {Object} [context.catalog] - Catalog override, for tests
+ * @returns {string} Physical secret name, or the key unchanged when the catalog says so
+ */
+function computePhysicalSecretName(key, context = {}) {
+  const logicalKey = String(key ?? '').trim();
+  if (!logicalKey) {
+    return logicalKey;
+  }
+  const entry = findCatalogEntry(logicalKey, context.catalog);
+  const azure = entry && entry.azure ? entry.azure : null;
+  if (!azure) {
+    return logicalKey;
+  }
+  if (azure.vaultSecretName) {
+    return String(azure.vaultSecretName);
+  }
+  if (!azure.vaultSecretNamePattern) {
+    return logicalKey;
+  }
+  // The owning application comes from the entry or from the key, never from the caller: an
+  // application-scoped parameter names its own owner, and a caller passing a different one
+  // would silently address another application's secret.
+  return applyVaultNamePattern(azure.vaultSecretNamePattern, logicalKey, {
+    environment: context.environment,
+    serviceName: context.serviceName,
+    appKey: entry.ownerAppKey || extractDatabaseAppKey(logicalKey)
+  });
+}
+
+/**
+ * @param {string} key - Logical catalog key
+ * @param {Object} [override] - Catalog override, for tests
+ * @returns {Object|null}
+ */
+function findCatalogEntry(key, override) {
+  const catalog = override || loadCatalogQuietly();
+  if (!catalog || typeof catalog.findEntryForKey !== 'function') {
+    return null;
+  }
+  try {
+    return catalog.findEntryForKey(key) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The catalog, or nothing.
+ *
+ * A key resolves to itself when the catalog cannot be read, which is the same answer an
+ * absent entry gives. Failing here instead would turn an unreadable catalog into "no secret
+ * resolves", and the catalog is already validated by its own checks.
+ *
+ * @returns {Object|null}
+ */
+function loadCatalogQuietly() {
+  try {
+    return require('./infra-parameter-catalog').getInfraParameterCatalog();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The name an environment-isolated installation must read.
+ *
+ * `computePhysicalSecretName` answers what the catalog declares. This answers what an
+ * environment may actually use, and the two differ in one place that matters.
+ *
+ * **An application-scoped secret is never shared between environments.** Each environment's
+ * application holds its own credential. Some catalog entries still pin a literal from before
+ * environments existed — `dataplane-client-secretKeyVault` names itself, with no
+ * `{environment}` anywhere — and honouring that in `pro` would hand `pro` the credential
+ * `dev` is using. One leaked client secret would then authenticate as the other environment's
+ * application, which is the whole isolation gone.
+ *
+ * So an app-scoped name that does not carry its environment gets one. System names
+ * (`keycloak-*`, `acr-*`) are left exactly as they are: there is one Keycloak and one
+ * registry per platform, and those secrets are shared on purpose.
+ *
+ * @param {string} key - Logical catalog key
+ * @param {string} environment - Environment key
+ * @returns {string} The secret name this environment must read
+ */
+function resolveStrictSecretName(key, environment) {
+  const logicalKey = String(key ?? '').trim();
+  const env = String(environment ?? '').trim().toLowerCase();
+  if (!logicalKey || !env) {
+    return logicalKey;
+  }
+  const physical = computePhysicalSecretName(logicalKey, { environment: env });
+  if (physical.startsWith(`${env}-`)) {
+    return physical;
+  }
+  const entry = findCatalogEntry(logicalKey);
+  // Unplaced keys are this installation's own and are scoped by environment; `system`,
+  // `infra` and `shared` entries are platform-wide and keep their names.
+  if (!entry || entry.scope === 'app') {
+    return `${env}-${physical}`;
+  }
+  return physical;
+}
+
+module.exports = {
+  extractDatabaseIndex,
+  extractDatabaseAppKey,
+  applyVaultNamePattern,
+  computePhysicalSecretName,
+  resolveStrictSecretName
+};