@aifabrix/builder 2.45.5 → 2.47.0

package/lib/utils/upload-pipeline-ui.js

@@ -16,6 +16,9 @@ const { formatProgress } = require('./cli-test-layout-chalk');
  * @returns {boolean}
  */
 function shouldShowUploadPipelineProgress(options = {}) {
+  if (options.suppressPipelineSpinner === true) {
+    return false;
+  }
   return options.json !== true;
 }
 
@@ -35,17 +38,21 @@ function shouldUseUploadPipelineSpinner(options = {}) {
  * @param {string} systemKey
  * @returns {string}
  */
-function buildUploadPipelineSpinnerLabel(systemKey) {
+function buildUploadPipelineSpinnerLabel(systemKey, opts = {}) {
+  if (opts.syncMode === true) {
+    return 'Checking config on dataplane…';
+  }
   const key = systemKey && String(systemKey).trim() ? String(systemKey).trim() : 'integration';
   return `Publishing ${key} to dataplane…`;
 }
 
 /**
  * @param {string} systemKey
+ * @param {Object} [opts]
  * @returns {string}
  */
-function buildUploadPipelineProgressText(systemKey) {
-  return formatProgress(buildUploadPipelineSpinnerLabel(systemKey));
+function buildUploadPipelineProgressText(systemKey, opts = {}) {
+  return formatProgress(buildUploadPipelineSpinnerLabel(systemKey, opts));
 }
 
 /**
@@ -64,12 +71,12 @@ async function runWithUploadPipelineSpinner(work, opts = {}) {
   }
 
   if (!shouldUseUploadPipelineSpinner(opts)) {
-    logger.log(buildUploadPipelineProgressText(opts.systemKey));
+    logger.log(buildUploadPipelineProgressText(opts.systemKey, opts));
     return work();
   }
 
   const ora = require('ora');
-  const label = buildUploadPipelineSpinnerLabel(opts.systemKey);
+  const label = buildUploadPipelineSpinnerLabel(opts.systemKey, opts);
   const spinner = ora({
     text: chalk.white(label),
     spinner: 'dots'

package/lib/utils/upload-sync-options.js

@@ -0,0 +1,42 @@
+/**
+ * Build options for `uploadExternalSystem` on test-command --sync paths.
+ *
+ * @fileoverview Minimal upload sync options (force, verbose)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} [options] - CLI options from test / sync callers
+ * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true }}
+ */
+function buildMinimalUploadSyncOptions(options = {}) {
+  const out = {
+    minimal: true,
+    // CLI -v on verify-* / test-* is for run output, not preflight upload banners.
+    verbose: false,
+    silentResolve: true,
+    syncMode: true,
+    suppressPipelineSpinner: options.suppressPipelineSpinner === true
+  };
+  if (options.force === true) {
+    out.force = true;
+  }
+  return out;
+}
+
+/**
+ * Minimal sync paths (verify-*, test --sync) always suppress upload sidecar chatter.
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function isQuietMinimalSync(options = {}) {
+  return options.minimal === true || options.syncMode === true;
+}
+
+module.exports = {
+  buildMinimalUploadSyncOptions,
+  isQuietMinimalSync
+};

package/lib/utils/url-declarative-public-base.js

@@ -51,6 +51,12 @@ function hostPortForProfile(profile, listenPort, developerIdNum) {
     : localHostPort(listenPort, developerIdNum);
 }
 
+function localhostFrontDoorBaseForMissingRemote(opts) {
+  const { profile, developerIdNum } = opts || {};
+  const port = hostPortForProfile(profile, 3000, developerIdNum);
+  return `http://localhost:${port}`.replace(/\/+$/, '');
+}
+
 /**
  * Scheme for `declarativePublicUrlsUseLocalhost` bases: always **http** for loopback reachability
  * (ignore `tlsEnabled` / `remote-server` https — localhost URLs are not served with TLS in dev).
@@ -155,14 +161,26 @@ function templateUsesRemoteHostPlaceholder(hostTemplate) {
  * @returns {string|null}
  */
 function buildTraefikPublicBaseIfApplicable(opts) {
-  const { traefik, pathActive, hostTemplate, developerIdRaw, remoteServer, infraTlsEnabled } =
-    opts;
+  const {
+    traefik,
+    pathActive,
+    hostTemplate,
+    developerIdRaw,
+    remoteServer,
+    infraTlsEnabled,
+    profile,
+    developerIdNum
+  } = opts;
   // Plan 124: Traefik host authority only when pathActive (traefik ∧ frontDoorRouting.enabled)
   if (!traefik || !pathActive || !hostTemplate || !String(hostTemplate).trim()) {
     return null;
   }
   if (templateUsesRemoteHostPlaceholder(hostTemplate) && !String(remoteServer || '').trim()) {
-    return null;
+    // Local full-platform (no remote domain): use the single localhost front door port (3000 + devId×100).
+    return localhostFrontDoorBaseForMissingRemote({
+      profile,
+      developerIdNum
+    });
   }
   const expanded = expandFrontDoorHostTemplateForUrls(hostTemplate, {
     developerIdRaw,

package/lib/utils/url-declarative-vdir-inactive-env.js

@@ -15,6 +15,7 @@ const yaml = require('js-yaml');
 const { existsSync, readFileSync } = require('../internal/fs-real-sync');
 const { DECLARATIVE_URL_INFRA_DEFAULTS } = require('./infra-env-defaults');
 const { computePathActive } = require('./url-declarative-url-flags');
+const { resolveInactiveVdirRewriteEnvKeys } = require('./app-relative-path-env');
 
 /**
  * Treat common YAML / string forms as enabled (strict `=== true` alone missed some parsers).
@@ -52,16 +53,22 @@ const INACTIVE_VDIR_PUBLIC_ENV_FALLBACK =
 /**
  * @param {string} content - .env template fragment
  * @param {string} replacement
+ * @param {ReadonlySet<string>} rewriteKeys
  * @returns {string}
  */
-function applyInactiveVdirPublicTokenRewrite(content, replacement) {
+function applyInactiveVdirPublicTokenRewrite(content, replacement, rewriteKeys) {
   if (!content || !content.includes(URL_DECLARATIVE_VDIR_PUBLIC_TOKEN)) {
     return content;
   }
   const escaped = URL_DECLARATIVE_VDIR_PUBLIC_TOKEN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   // End line with [ \t]* only — \s would consume \n and strip line endings from the file.
-  const lineRe = new RegExp(`^(\\s*[A-Z][A-Z0-9_]*)\\s*=\\s*${escaped}[ \t]*$`, 'gm');
-  return content.replace(lineRe, (_, lhs) => `${lhs}=${replacement}`);
+  const lineRe = new RegExp(`^(\\s*)([A-Z][A-Z0-9_]*)\\s*=\\s*${escaped}[ \t]*$`, 'gm');
+  return content.replace(lineRe, (match, indent, key) => {
+    if (!rewriteKeys.has(key)) {
+      return match;
+    }
+    return `${indent}${key}=${replacement}`;
+  });
 }
 
 /**
@@ -88,12 +95,15 @@ function rewriteInactiveDeclarativeVdirPublicContent(content, variablesPath, use
   if (pathActive) {
     return content;
   }
-  return applyInactiveVdirPublicTokenRewrite(content, INACTIVE_VDIR_PUBLIC_ENV_FALLBACK);
+  const appKey = doc && doc.app && doc.app.key;
+  const rewriteKeys = resolveInactiveVdirRewriteEnvKeys(appKey);
+  return applyInactiveVdirPublicTokenRewrite(content, INACTIVE_VDIR_PUBLIC_ENV_FALLBACK, rewriteKeys);
 }
 
 module.exports = {
   URL_DECLARATIVE_VDIR_PUBLIC_TOKEN,
   INACTIVE_VDIR_PUBLIC_ENV_FALLBACK,
+  loadApplicationYamlDoc,
   applyInactiveVdirPublicTokenRewrite,
   rewriteInactiveDeclarativeVdirPublicContent,
   isFrontDoorRoutingEnabledInDoc

package/lib/utils/validation-poll-ui.js

@@ -48,6 +48,14 @@ const NON_TTY_THROTTLE_MS = 5000;
  * @returns {{ usesSpinner: boolean, onPollProgress: Function, finish: () => void }}
  */
 function createValidationPollHandlers(deadlineMs, opts = {}) {
+  if (opts.quiet === true) {
+    return {
+      usesSpinner: false,
+      onPollProgress: () => {},
+      finish: () => {}
+    };
+  }
+
   const subject = opts.subject;
   if (shouldUseValidationPollSpinner()) {
     const ora = require('ora');

package/lib/utils/validation-run-stage.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Map legacy validation runType to contract stage (dataplane 370.07).
+ */
+
+'use strict';
+
+/** @typedef {'readiness'|'simulation'|'integration'|'e2e'} ValidationRunStage */
+
+/** @type {Record<string, ValidationRunStage>} */
+const RUN_TYPE_TO_STAGE = {
+  test: 'readiness',
+  integration: 'integration',
+  e2e: 'e2e'
+};
+
+/**
+ * Contract stage for a CLI/API runType (default product mapping).
+ * @param {string} runType - test | integration | e2e
+ * @returns {ValidationRunStage}
+ */
+function stageForRunType(runType) {
+  const key = String(runType || 'test');
+  return RUN_TYPE_TO_STAGE[key] || 'readiness';
+}
+
+/**
+ * Attach stage to a validation/run POST body when absent.
+ * @param {Object} body
+ * @param {string} [runType]
+ * @returns {Object}
+ */
+function withStageOnValidationRunBody(body, runType) {
+  const out = { ...body };
+  const rt = runType || out.runType || 'test';
+  if (!out.stage) {
+    out.stage = stageForRunType(rt);
+  }
+  return out;
+}
+
+module.exports = {
+  RUN_TYPE_TO_STAGE,
+  stageForRunType,
+  withStageOnValidationRunBody
+};

package/lib/utils/worker-sidecars.js

@@ -0,0 +1,142 @@
+/**
+ * Worker sidecar resolution from application.yaml build settings.
+ *
+ * @fileoverview Generic worker/beat companions driven by build.worker and imageRun* fields
+ */
+
+'use strict';
+
+const { buildDefaultLocalContainerName } = require('./environment-scoped-resources');
+
+/**
+ * @param {object|null|undefined} build
+ * @param {string} field
+ * @returns {string|null}
+ */
+function readImageRunCommand(build, field) {
+  if (!build || typeof build !== 'object') {
+    return null;
+  }
+  const raw = build[field];
+  if (typeof raw !== 'string') {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed ? trimmed : null;
+}
+
+/**
+ * @param {object|null|undefined} appConfig
+ * @returns {boolean}
+ */
+function isWorkerStackEnabled(appConfig) {
+  if (!appConfig || typeof appConfig !== 'object') {
+    return false;
+  }
+  return appConfig.build?.worker === true;
+}
+
+/**
+ * @param {string} appKey
+ * @param {object|null|undefined} appConfig
+ * @returns {{
+ *   enabled: boolean,
+ *   worker: { key: string, command: string }|null,
+ *   beat: { key: string, command: string }|null,
+ *   companions: Array<{ role: string, key: string, command: string }>
+ * }}
+ */
+function resolveWorkerSidecars(appKey, appConfig) {
+  const empty = { enabled: false, worker: null, beat: null, companions: [] };
+  if (!isWorkerStackEnabled(appConfig)) {
+    return empty;
+  }
+
+  const build = appConfig.build && typeof appConfig.build === 'object' ? appConfig.build : {};
+  const workerCommand = readImageRunCommand(build, 'imageRunWorker');
+  const beatCommand = readImageRunCommand(build, 'imageRunBeat');
+  const companions = [];
+
+  if (workerCommand) {
+    companions.push({ role: 'worker', key: `${appKey}-worker`, command: workerCommand });
+  }
+  if (beatCommand) {
+    companions.push({ role: 'beat', key: `${appKey}-beat`, command: beatCommand });
+  }
+
+  if (companions.length === 0) {
+    return empty;
+  }
+
+  const worker = companions.find((entry) => entry.role === 'worker') || null;
+  const beat = companions.find((entry) => entry.role === 'beat') || null;
+
+  return {
+    enabled: true,
+    worker,
+    beat,
+    companions
+  };
+}
+
+/**
+ * @param {string} appKey
+ * @param {object|null|undefined} appConfig
+ * @returns {string[]}
+ */
+function getWorkerCompanionAppKeys(appKey, appConfig) {
+  return resolveWorkerSidecars(appKey, appConfig).companions.map((entry) => entry.key);
+}
+
+/**
+ * @param {string} appKey
+ * @param {object} appConfig
+ * @param {{ devId: string|number, idNum: number }} ids
+ * @returns {{
+ *   enabled: boolean,
+ *   worker?: { key: string, containerName: string, command: string },
+ *   beat?: { key: string, containerName: string, command: string }
+ * }}
+ */
+function buildWorkerSidecarComposeContext(appKey, appConfig, ids) {
+  const sidecars = resolveWorkerSidecars(appKey, appConfig);
+  if (!sidecars.enabled) {
+    return { enabled: false };
+  }
+
+  const context = { enabled: true };
+  if (sidecars.worker) {
+    context.worker = {
+      key: sidecars.worker.key,
+      containerName: buildDefaultLocalContainerName(sidecars.worker.key, ids.devId, ids.idNum),
+      command: sidecars.worker.command
+    };
+  }
+  if (sidecars.beat) {
+    context.beat = {
+      key: sidecars.beat.key,
+      containerName: buildDefaultLocalContainerName(sidecars.beat.key, ids.devId, ids.idNum),
+      command: sidecars.beat.command
+    };
+  }
+  return context;
+}
+
+/**
+ * Azure startupCommand from compose imageRun (drops leading exec).
+ *
+ * @param {string} imageRun
+ * @returns {string}
+ */
+function imageRunToStartupCommand(imageRun) {
+  return imageRun.replace(/^exec\s+/i, '').trim();
+}
+
+module.exports = {
+  readImageRunCommand,
+  isWorkerStackEnabled,
+  resolveWorkerSidecars,
+  getWorkerCompanionAppKeys,
+  buildWorkerSidecarComposeContext,
+  imageRunToStartupCommand
+};

package/lib/validation/external-manifest-validator.js

@@ -16,6 +16,7 @@ const path = require('path');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
 const { validateAbac } = require('../datasource/abac-validator');
+const { validateManifestRuntimeConfiguration } = require('./runtime-configuration-rules');
 
 /**
  * Load and normalize external-system + external-datasource schema objects for manifest AJV.
@@ -247,6 +248,7 @@ async function validateControllerManifest(manifest) {
   validateInlineSystem(manifest, ajv, externalSystemSchema, errors);
   validateDatasources(manifest, ajv, externalDatasourceSchema, errors, warnings);
   validateDatasourceSystemKeyAlignment(manifest, errors);
+  errors.push(...validateManifestRuntimeConfiguration(manifest));
   validateConditionalRequirements(manifest, errors, warnings);
   validateRequiredFields(manifest, errors);
 

package/lib/validation/runtime-configuration-rules.js

@@ -0,0 +1,98 @@
+/**
+ * Runtime configuration validation for external system manifests.
+ *
+ * @fileoverview Datasource override rules (v1: no keyvault overrides)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @param {Array<{ name?: string, location?: string }>|undefined} systemConfiguration
+ * @returns {Map<string, { name?: string, location?: string }>}
+ */
+function systemConfigDefsByName(systemConfiguration) {
+  const defsByName = new Map();
+  for (const item of systemConfiguration || []) {
+    if (item && item.name) {
+      defsByName.set(String(item.name).trim(), item);
+    }
+  }
+  return defsByName;
+}
+
+/**
+ * @param {string} prefix
+ * @param {Map<string, { name?: string, location?: string }>} defsByName
+ * @param {{ name?: string, value?: string }} override
+ * @returns {string[]}
+ */
+function validateOverrideEntry(prefix, defsByName, override) {
+  if (!override || !override.name) {
+    return [];
+  }
+  const name = String(override.name).trim();
+  const def = defsByName.get(name);
+  if (!def) {
+    return [`${prefix}configuration override '${name}' is not declared on the parent system.`];
+  }
+  const errors = [];
+  if (String(def.location || 'variable').toLowerCase() === 'keyvault') {
+    errors.push(
+      `${prefix}configuration override '${name}' targets a keyvault system definition (not allowed in v1).`
+    );
+  }
+  const extraKeys = Object.keys(override).filter((key) => key !== 'name' && key !== 'value');
+  if (extraKeys.length > 0) {
+    errors.push(
+      `${prefix}configuration override '${name}' must contain only name and value (found: ${extraKeys.join(', ')}).`
+    );
+  }
+  return errors;
+}
+
+/**
+ * Validates datasource configuration[] overrides against parent system definitions.
+ *
+ * @param {Array<{ name?: string, location?: string }>|undefined} systemConfiguration
+ * @param {Array<{ name?: string, value?: string }>|undefined} datasourceConfiguration
+ * @param {string} [datasourceKey] - For error prefixes
+ * @returns {string[]} Validation errors
+ */
+function validateDatasourceConfigurationOverrides(
+  systemConfiguration,
+  datasourceConfiguration,
+  datasourceKey
+) {
+  if (!Array.isArray(datasourceConfiguration) || datasourceConfiguration.length === 0) {
+    return [];
+  }
+  const prefix = datasourceKey ? `Datasource '${datasourceKey}': ` : '';
+  const defsByName = systemConfigDefsByName(systemConfiguration);
+  return datasourceConfiguration.flatMap((override) =>
+    validateOverrideEntry(prefix, defsByName, override)
+  );
+}
+
+/**
+ * @param {{ system?: { configuration?: unknown[] }, dataSources?: Array<{ key?: string, configuration?: unknown[] }> }} manifest
+ * @returns {string[]}
+ */
+function validateManifestRuntimeConfiguration(manifest) {
+  const errors = [];
+  const systemConfiguration = manifest?.system?.configuration;
+  for (const ds of manifest?.dataSources || []) {
+    errors.push(
+      ...validateDatasourceConfigurationOverrides(
+        systemConfiguration,
+        ds?.configuration,
+        ds?.key
+      )
+    );
+  }
+  return errors;
+}
+
+module.exports = {
+  validateDatasourceConfigurationOverrides,
+  validateManifestRuntimeConfiguration
+};

package/lib/validation/validate-display-dimensions.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Dimensions (ABAC) display helpers for validate-display.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { loadConfigFile } = require('../utils/config-format');
+const { flattenRootDimensionsForDisplay } = require('./dimension-display-helpers');
+const { formatDatasourceListRow } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+const {
+  logSectionTitle,
+  logWarnRow,
+  logDimLine
+} = require('./validate-display-log-helpers');
+
+/**
+ * True when datasource is orchestration-only (no ABAC dimensions contract).
+ * @param {string} filePath - Path to datasource JSON
+ * @returns {boolean}
+ */
+function isOrchestrationOnlyDatasource(filePath) {
+  try {
+    const parsed = loadConfigFile(filePath);
+    return String(parsed?.entityType || '').trim() === 'none';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extracts dimensions from a datasource file for CLI display.
+ * Local bindings become `metadata.<field>`; FK bindings become `fk:<fk>→<dimension>...` plus optional `(actor: ...)`.
+ * @function extractDimensionsFromDatasource
+ * @param {string} filePath - Path to datasource file
+ * @returns {Object} Dimensions info { dimensions: Object, dimensionKeys: string[], hasDimensions: boolean }
+ */
+function extractDimensionsFromDatasource(filePath) {
+  try {
+    const parsed = loadConfigFile(filePath);
+
+    const rootFlat = flattenRootDimensionsForDisplay(parsed.dimensions);
+    const abacDimensions = parsed.abac?.dimensions || {};
+    const allDimensions = { ...rootFlat, ...abacDimensions };
+    const dimensionKeys = Object.keys(allDimensions);
+
+    return {
+      dimensions: allDimensions,
+      dimensionKeys,
+      hasDimensions: dimensionKeys.length > 0
+    };
+  } catch {
+    return { dimensions: {}, dimensionKeys: [], hasDimensions: false };
+  }
+}
+
+/**
+ * Displays Dimensions (ABAC) validation results for datasources
+ * @function displayDimensionsValidation
+ * @param {Array} externalFiles - External files validation results
+ * @returns {Array} Warnings to add to aggregated warnings
+ */
+function displayDimensionsValidation(externalFiles) {
+  if (!externalFiles || externalFiles.length === 0) {
+    return [];
+  }
+
+  const datasourceFiles = externalFiles.filter(f =>
+    f.type === 'datasource' || f.type === 'external-datasource'
+  );
+
+  if (datasourceFiles.length === 0) {
+    return [];
+  }
+
+  logSectionTitle('Dimensions (ABAC)');
+
+  const warnings = [];
+  let anyDatasourceHasDimensions = false;
+
+  datasourceFiles.forEach(file => {
+    if (file.path && isOrchestrationOnlyDatasource(file.path)) {
+      logger.log(formatDatasourceListRow('ok', file.file, file.type));
+      logDimLine('orchestration-only (entityType=none) — dimensions N/A');
+      return;
+    }
+    const dimensionsInfo = extractDimensionsFromDatasource(file.path);
+
+    if (dimensionsInfo.hasDimensions) {
+      anyDatasourceHasDimensions = true;
+      logger.log(formatDatasourceListRow('ok', file.file, file.type));
+      dimensionsInfo.dimensionKeys.forEach(key => {
+        const mapping = dimensionsInfo.dimensions[key];
+        logDimLine(`${key} → ${mapping}`);
+      });
+    } else {
+      logWarnRow(`${file.file} — no dimensions configured`);
+      warnings.push(`${file.file} - no dimensions configured, ABAC filtering disabled`);
+    }
+  });
+
+  if (!anyDatasourceHasDimensions && datasourceFiles.some(
+    (file) => !(file.path && isOrchestrationOnlyDatasource(file.path))
+  )) {
+    logWarnRow('No dimensions configured — ABAC filtering disabled for all datasources');
+  }
+
+  return warnings;
+}
+
+/**
+ * Displays dimensions validation for datasources
+ * @function displayDimensionsStep
+ * @param {Array} datasourceFiles - Datasource files
+ * @returns {void}
+ */
+function displayDimensionsStep(datasourceFiles) {
+  if (datasourceFiles.length === 0) {
+    return;
+  }
+
+  logSectionTitle('Dimensions (ABAC)');
+  datasourceFiles.forEach(file => {
+    try {
+      const dsPath = file.path || file.file;
+      if (dsPath && isOrchestrationOnlyDatasource(dsPath)) {
+        logger.log(formatDatasourceListRow('ok', file.file, file.type));
+        logDimLine('orchestration-only (entityType=none) — dimensions N/A');
+        return;
+      }
+      const dimensionsInfo = extractDimensionsFromDatasource(dsPath);
+      if (dimensionsInfo.hasDimensions) {
+        logger.log(formatDatasourceListRow('ok', file.file, file.type));
+        dimensionsInfo.dimensionKeys.forEach(key => {
+          const mapping = dimensionsInfo.dimensions[key];
+          logDimLine(`${key} → ${mapping}`);
+        });
+      } else {
+        logWarnRow(`${file.file} — no dimensions configured`);
+      }
+    } catch {
+      // Skip if file path not available
+    }
+  });
+}
+
+module.exports = {
+  isOrchestrationOnlyDatasource,
+  extractDimensionsFromDatasource,
+  displayDimensionsValidation,
+  displayDimensionsStep
+};