@aifabrix/builder 2.44.6 → 2.45.5

package/lib/utils/cli-exit-codes.js

@@ -0,0 +1,30 @@
+/**
+ * Canonical Builder CLI exit codes for scriptable commands.
+ *
+ * Documented in `docs/commands/authentication.md`. Use in
+ * `aifabrix auth status --validate` and any future `--validate`-style flag.
+ *
+ * @fileoverview Exit-code constants for scriptable Builder CLI commands
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/** Success. */
+const EXIT_OK = 0;
+
+/** Not authenticated / invalid token. */
+const EXIT_NOT_AUTHENTICATED = 1;
+
+/**
+ * Authenticated but installed Builder CLI version is older than the dataplane
+ * minimum advertised by `GET /api/v1/health → minBuilderCliVersion` (plan 403.0).
+ */
+const EXIT_CLI_VERSION_INCOMPATIBLE = 3;
+
+module.exports = {
+  EXIT_OK,
+  EXIT_NOT_AUTHENTICATED,
+  EXIT_CLI_VERSION_INCOMPATIBLE
+};

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

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Detect skip-sync from Commander options and raw argv (--no-sync → sync: false).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * True when the user passed `--no-sync` or Commander set `sync: false` / `noSync: true`.
+ * Do not use for `protection upload --no-sync` (post-upload datasource sync only).
+ *
+ * @param {Object|null|undefined} options - Commander-parsed options
+ * @param {import('commander').Command} [cmd] - Commander command (for rawArgs fallback)
+ * @returns {boolean}
+ */
+function cliOptsSkipSync(options, cmd) {
+  if (!options || typeof options !== 'object') {
+    return false;
+  }
+  if (options.noSync === true) {
+    return true;
+  }
+  if (options.sync === false) {
+    return true;
+  }
+  const raw = cmd && Array.isArray(cmd.rawArgs) ? cmd.rawArgs : [];
+  return raw.includes('--no-sync');
+}
+
+module.exports = {
+  cliOptsSkipSync
+};

package/lib/utils/compose-generate-docker-compose.js

@@ -15,6 +15,99 @@ const paths = require('./paths');
 const { getInfraDirName } = require('../infrastructure/helpers');
 const { resolveMisoEnvironment } = require('./compose-miso-env');
 
+/**
+ * When running a pulled Python image (no bind-mounted source), the image CMD may invoke the
+ * `uvicorn` console script, which is not always on PATH. Derive a `python -m uvicorn` command from
+ * `build.reloadStart` so generated compose matches the same app entrypoint as hot-reload runs.
+ *
+ * @param {string|undefined} reloadStart - Value from application.yaml `build.reloadStart`
+ * @returns {string|null} Shell command fragment (no `cd`, no `exec`; image compose prepends `exec ` in JS)
+ */
+function derivePythonImageStartFromReload(reloadStart) {
+  if (typeof reloadStart !== 'string' || !reloadStart.trim()) {
+    return null;
+  }
+  const trimmed = reloadStart.trim().replace(/\s+--reload\b/g, '').trim();
+  if (/^python3?\s+-m\s+uvicorn\s+/i.test(trimmed)) {
+    return normalizeComposeShellPortRef(trimmed);
+  }
+  if (trimmed.startsWith('uvicorn ')) {
+    const rest = trimmed.slice('uvicorn '.length);
+    return normalizeComposeShellPortRef(`python -m uvicorn ${rest}`);
+  }
+  return null;
+}
+
+/**
+ * Compose sets `PORT` in the service environment; replace `${PORT:-...}` with `$$PORT` in the
+ * fragment so the compose file avoids ambiguous `:` parsing in flow scalars and Compose expands
+ * `$$` to `$` for the container shell (which then expands `PORT` from the service environment).
+ *
+ * @param {string} cmd - Shell command fragment
+ * @returns {string} Same fragment with `${PORT:-...}` replaced by `$$PORT` (Compose escapes `$$` → `$` for the shell)
+ */
+function normalizeComposeShellPortRef(cmd) {
+  return cmd.replace(/\$\{PORT:-[^}]+\}/g, () => '$$PORT');
+}
+
+/**
+ * Normalizes `build.reloadStart` for Python when using a bind-mounted source in compose.
+ *
+ * @param {string} raw - Trimmed reload command
+ * @returns {string} Command suitable for `cd /app && …` in compose
+ */
+function normalizePythonReloadForComposeMounted(raw) {
+  const s = normalizeComposeShellPortRef(raw);
+  if (/^python3?\s+-m\s+uvicorn\s+/i.test(s)) {
+    return s;
+  }
+  if (s.startsWith('uvicorn ')) {
+    return `python -m uvicorn ${s.slice('uvicorn '.length)}`;
+  }
+  return s;
+}
+
+/**
+ * Builds the single `reloadStartCommand` passed to compose templates (`command: …` when set).
+ *
+ * `applications.<app>.reload` in config.yaml (and `aifabrix run --reload`) only controls **bind-mount +
+ * `--reload`** via `devMountPath`. For pulled images without a mount, use optional `build.imageRun` in
+ * application.yaml, or (Python only) derive from `build.reloadStart` when `imageRun` is unset.
+ *
+ * @param {string} language - `application.yaml` build.language
+ * @param {string|null} devMountPath - Bind mount path when reload sync is active
+ * @param {string|undefined} reloadRaw - `build.reloadStart`
+ * @param {Object} [build] - `application.yaml` `build` object (`imageRun`, etc.)
+ * @returns {string|null}
+ */
+function buildReloadStartCommandForCompose(language, devMountPath, reloadRaw, build = {}) {
+  const buildObj = build && typeof build === 'object' ? build : {};
+  const imageRunRaw = typeof buildObj.imageRun === 'string' ? buildObj.imageRun.trim() : '';
+  const reloadTrimmed = typeof reloadRaw === 'string' ? reloadRaw.trim() : '';
+
+  if (devMountPath) {
+    if (!reloadTrimmed) {
+      return null;
+    }
+    return language === 'python' ? normalizePythonReloadForComposeMounted(reloadTrimmed) : reloadTrimmed;
+  }
+
+  if (imageRunRaw) {
+    return normalizeComposeShellPortRef(imageRunRaw);
+  }
+
+  if (!reloadTrimmed) {
+    return null;
+  }
+
+  if (language === 'python') {
+    const imageCmd = derivePythonImageStartFromReload(reloadTrimmed);
+    return imageCmd ? `exec ${imageCmd}` : null;
+  }
+
+  return null;
+}
+
 /**
  * Resolve infra `pgpass` path: prefer system config dir; when home differs, allow legacy layout.
  * @param {string|number} devId - Developer id (infra vs infra-dev{n})
@@ -119,14 +212,15 @@ async function loadComposeHead(deps, appName, appConfig, options) {
  * @param {object} head - From loadComposeHead
  * @returns {object}
  */
-function buildComposeLayouts(deps, appName, appConfig, head) {
+function buildComposeLayouts(deps, appName, appConfig, head, options) {
   const { buildNetworkAndContainerNames, buildServiceConfig, buildVolumesConfig, buildNetworksConfig } = deps;
   const { port, imageOverride, devId, idNum, scoped, remoteServer } = head;
   const { networkName, containerName } = buildNetworkAndContainerNames(appName, devId, idNum, scoped);
   const serviceConfig = buildServiceConfig(appName, appConfig, port, devId, {
     imageOverride,
     scopeOpts: scoped,
-    remoteServer
+    remoteServer,
+    omitAppTraefikLabels: options && options.omitAppTraefikLabels === true
   });
   const volumesConfig = buildVolumesConfig(appName);
   const networksConfig = buildNetworksConfig(appConfig);
@@ -161,8 +255,13 @@ async function resolveComposePathsAndSecrets(ctx) {
   );
   const devMountPath = resolveDevMountPath(options);
   const reloadRaw = appConfig.build?.reloadStart;
-  const reloadStartCommand =
-    devMountPath && typeof reloadRaw === 'string' && reloadRaw.trim().length > 0 ? reloadRaw.trim() : null;
+  const language = appConfig.build?.language || appConfig.language || 'typescript';
+  const reloadStartCommand = buildReloadStartCommandForCompose(
+    language,
+    devMountPath,
+    reloadRaw,
+    appConfig.build
+  );
   const infraPgpassPath = resolveInfraPgpassPath(devId, paths, fsSync.existsSync);
   const useInfraPgpass = serviceCf.requiresDatabase && fsSync.existsSync(infraPgpassPath);
   return {
@@ -185,7 +284,7 @@ async function resolveComposePathsAndSecrets(ctx) {
  */
 async function generateDockerComposeImpl(deps, appName, appConfig, options) {
   const head = await loadComposeHead(deps, appName, appConfig, options);
-  const layouts = buildComposeLayouts(deps, appName, appConfig, head);
+  const layouts = buildComposeLayouts(deps, appName, appConfig, head, options);
   const side = await resolveComposePathsAndSecrets({
     options,
     appName,
@@ -213,4 +312,10 @@ function createGenerateDockerCompose(deps) {
   return (appName, appConfig, options) => generateDockerComposeImpl(deps, appName, appConfig, options);
 }
 
-module.exports = { createGenerateDockerCompose, resolveInfraPgpassPath };
+module.exports = {
+  createGenerateDockerCompose,
+  resolveInfraPgpassPath,
+  derivePythonImageStartFromReload,
+  buildReloadStartCommandForCompose,
+  normalizePythonReloadForComposeMounted
+};

package/lib/utils/compose-generator.js

@@ -282,10 +282,16 @@ function buildRequiresConfig(config) {
  * @param {string} [runExtras.imageOverride] - Full image reference for run (e.g. from --image)
  * @param {Object|null} [runExtras.scopeOpts] - Traefik / scoped compose options
  * @param {string|null|undefined} [runExtras.remoteServer] - For ${REMOTE_HOST} in frontDoorRouting.host
+ * @param {boolean} [runExtras.omitAppTraefikLabels] - When true (user config `traefik: false`), omit Traefik labels and BASE_PATH env from compose even if application.yaml enables frontDoorRouting
  * @returns {Object} Service configuration
  */
 function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
-  const { imageOverride = null, scopeOpts = null, remoteServer = null } = runExtras;
+  const {
+    imageOverride = null,
+    scopeOpts = null,
+    remoteServer = null,
+    omitAppTraefikLabels = false
+  } = runExtras;
   const containerPortValue = getContainerPort(config, 3000);
   const hostPort = port;
   const useTraefikScope =
@@ -305,13 +311,16 @@ function buildServiceConfig(appName, config, port, devId, runExtras = {}) {
     containerPort: containerPortValue, // Container port (always set, equals containerPort if exists, else port)
     hostPort: hostPort, // Host port (options.port if provided, else config.port)
     healthCheck,
-    traefik: buildTraefikConfig(
-      config,
-      devId,
-      scopeForHealthAndTraefik,
-      remoteServer,
-      healthCheck.path
-    ),
+    traefik:
+      omitAppTraefikLabels === true
+        ? { enabled: false }
+        : buildTraefikConfig(
+          config,
+          devId,
+          scopeForHealthAndTraefik,
+          remoteServer,
+          healthCheck.path
+        ),
     ...buildRequiresConfig(config)
   };
 }

package/lib/utils/controller-url.js

@@ -42,8 +42,38 @@ function normalizeUrl(url) {
 }
 
 /**
- * Get controller URL from logged-in user's device tokens
- * Returns the first available controller URL from device tokens stored in config
+ * True when `config.yaml` has a non-expired-looking device entry for this controller URL
+ * (normalized host/path comparison).
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<boolean>}
+ */
+async function hasStoredDeviceTokenForController(controllerUrl) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    return false;
+  }
+  const want = normalizeUrl(controllerUrl);
+  if (!want) {
+    return false;
+  }
+  try {
+    const userConfig = await config.getConfig();
+    if (!userConfig.device || typeof userConfig.device !== 'object') {
+      return false;
+    }
+    return Object.keys(userConfig.device).some((key) => normalizeUrl(key) === want);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get controller URL from logged-in user's device tokens.
+ * Prefers the entry under {@link config.controller} when it matches a `device` key; otherwise a
+ * single `device` entry; with multiple unrelated entries and no matching default, returns **null**
+ * (callers must not treat arbitrary key order as the active controller).
+ *
  * @async
  * @function getControllerUrlFromLoggedInUser
  * @returns {Promise<string|null>} Controller URL from logged-in user, or null if not found
@@ -60,11 +90,23 @@ async function getControllerUrlFromLoggedInUser() {
       return null;
     }
 
-    // Return the first available controller URL (normalized)
-    const firstControllerUrl = deviceUrls[0];
-    return normalizeUrl(firstControllerUrl);
-  } catch (error) {
-    // If config doesn't exist or can't be read, return null
+    const cfgController =
+      userConfig.controller && typeof userConfig.controller === 'string'
+        ? normalizeUrl(userConfig.controller)
+        : '';
+    if (cfgController) {
+      const match = deviceUrls.find((u) => normalizeUrl(u) === cfgController);
+      if (match) {
+        return normalizeUrl(match);
+      }
+    }
+
+    if (deviceUrls.length === 1) {
+      return normalizeUrl(deviceUrls[0]);
+    }
+
+    return null;
+  } catch {
     return null;
   }
 }
@@ -109,6 +151,7 @@ async function resolveControllerUrl() {
 
 module.exports = {
   getDefaultControllerUrl,
+  hasStoredDeviceTokenForController,
   getControllerUrlFromLoggedInUser,
   getControllerFromConfig,
   resolveControllerUrl

package/lib/utils/credential-push-ui.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Progress line + optional in-place spinner for credential secret push.
+ * @author AI Fabrix Team
+ * @version 1.2.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { formatProgress } = require('./cli-test-layout-chalk');
+
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.json] - When true, skip progress line and spinner
+ * @returns {boolean}
+ */
+function shouldShowCredentialPushProgress(options = {}) {
+  return options.json !== true;
+}
+
+/**
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function shouldUseCredentialPushSpinner(options = {}) {
+  if (!shouldShowCredentialPushProgress(options)) {
+    return false;
+  }
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function buildCredentialPushSpinnerLabel(systemKey) {
+  const key = systemKey && String(systemKey).trim() ? String(systemKey).trim() : 'integration';
+  return `Pushing credential secrets for ${key}…`;
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function buildCredentialPushSpinnerText(systemKey) {
+  return formatProgress(buildCredentialPushSpinnerLabel(systemKey));
+}
+
+/**
+ * Run credential push work with visible progress (⏳ line or ora with label on TTY).
+ *
+ * @async
+ * @param {Function} work - Zero-arg async function performing the push
+ * @param {Object} [opts]
+ * @param {string} [opts.systemKey]
+ * @param {boolean} [opts.json]
+ * @returns {Promise<*>}
+ */
+async function runWithCredentialPushSpinner(work, opts = {}) {
+  if (!shouldShowCredentialPushProgress(opts)) {
+    return work();
+  }
+
+  if (!shouldUseCredentialPushSpinner(opts)) {
+    logger.log(buildCredentialPushSpinnerText(opts.systemKey));
+    return work();
+  }
+
+  const ora = require('ora');
+  const label = buildCredentialPushSpinnerLabel(opts.systemKey);
+  const spinner = ora({
+    text: chalk.white(label),
+    spinner: 'dots'
+  }).start();
+
+  try {
+    return await work();
+  } finally {
+    spinner.stop();
+  }
+}
+
+module.exports = {
+  shouldShowCredentialPushProgress,
+  shouldUseCredentialPushSpinner,
+  buildCredentialPushSpinnerLabel,
+  buildCredentialPushSpinnerText,
+  runWithCredentialPushSpinner
+};

package/lib/utils/dataplane-cli-version-gate.js

@@ -0,0 +1,202 @@
+/**
+ * Builder CLI ↔ dataplane version gate (plan 142.0).
+ *
+ * Resolves the dataplane-advertised `minBuilderCliVersion` (from cache or a
+ * fresh health probe) and compares it against the installed Builder CLI
+ * version. Used at the top of dataplane API entrypoints so an outdated CLI
+ * cannot mutate dataplane state silently.
+ *
+ * Local-only commands (validate, run, up-infra, file generation) do **not**
+ * call into this module; the gate is intentionally per-call, not global.
+ *
+ * @fileoverview Compatibility gate for dataplane API entrypoints
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+const {
+  getDeviceDataplaneVersions,
+  updateDeviceDataplaneVersions,
+  isCacheStale
+} = require('../core/config-device-dataplane');
+const { compareSemver, isValidSemver } = require('./semver-compare');
+const { formatCliVersionGateError } = require('./dataplane-cli-version-help');
+
+/**
+ * Get the installed Builder CLI version from `package.json`.
+ * Centralized so tests can stub it via Jest module mocks.
+ * @returns {string}
+ */
+function getInstalledCliVersion() {
+  return require('../../package.json').version;
+}
+
+/**
+ * Internal sentinel error code so callers can distinguish gate failures from
+ * generic dataplane errors when needed.
+ * @type {string}
+ */
+const ERROR_CODE = 'CLI_VERSION_INCOMPATIBLE';
+
+/**
+ * True when `err` was thrown by this gate.
+ * @param {*} err
+ * @returns {boolean}
+ */
+function isCliVersionIncompatibleError(err) {
+  return Boolean(err && err.code === ERROR_CODE);
+}
+
+/**
+ * Resolve the dataplane minimum Builder CLI version, preferring cached value
+ * when fresh; otherwise probe health and persist a new snapshot under
+ * `device.<controllerUrl>`.
+ *
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {string} dataplaneUrl
+ * @param {{ forceRefresh?: boolean }} [options]
+ * @returns {Promise<{ minBuilderCliVersion?: string, dataplaneVersion?: string }>}
+ */
+async function resolveMinBuilderCliVersion(controllerUrl, dataplaneUrl, options = {}) {
+  const forceRefresh = Boolean(options.forceRefresh);
+  if (!forceRefresh) {
+    const cached = await safeReadCache(controllerUrl);
+    if (cached && !isCacheStale(cached)) {
+      return {
+        minBuilderCliVersion: cached.minBuilderCliVersion,
+        dataplaneVersion: cached.version
+      };
+    }
+  }
+
+  const snapshot = await safeFetch(dataplaneUrl);
+  if (!snapshot) {
+    // Cannot reach dataplane → do not gate (offline / pre-rollout). Reuse
+    // any cached value we may have.
+    const cached = await safeReadCache(controllerUrl);
+    return {
+      minBuilderCliVersion: cached ? cached.minBuilderCliVersion : undefined,
+      dataplaneVersion: cached ? cached.version : undefined
+    };
+  }
+
+  await safeWriteCache(controllerUrl, {
+    version: snapshot.version,
+    minBuilderCliVersion: snapshot.minBuilderCliVersion || null
+  });
+  return {
+    minBuilderCliVersion: snapshot.minBuilderCliVersion,
+    dataplaneVersion: snapshot.version
+  };
+}
+
+/**
+ * Read cached versions without throwing — gate failures should not mask real
+ * dataplane errors caused by config corruption.
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<Object|null>}
+ */
+async function safeReadCache(controllerUrl) {
+  if (!controllerUrl) return null;
+  try {
+    return await getDeviceDataplaneVersions(controllerUrl);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Fetch health swallowing transport errors so callers can decide what to do
+ * when the dataplane is unreachable.
+ * @private
+ * @async
+ * @param {string} dataplaneUrl
+ * @returns {Promise<Object|null>}
+ */
+async function safeFetch(dataplaneUrl) {
+  try {
+    return await fetchDataplaneGeneralHealth(dataplaneUrl);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * Write the cache without throwing — best-effort persistence.
+ * @private
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} versions
+ * @returns {Promise<void>}
+ */
+async function safeWriteCache(controllerUrl, versions) {
+  if (!controllerUrl) return;
+  try {
+    await updateDeviceDataplaneVersions(controllerUrl, versions);
+  } catch (_error) {
+    // intentionally swallowed — cache write failure must not block the call
+  }
+}
+
+/**
+ * Throw when the installed CLI is older than the dataplane minimum.
+ *
+ * No-op when:
+ *   - `dataplaneUrl` is empty (no dataplane in play)
+ *   - Dataplane omits `minBuilderCliVersion` (no enforcement)
+ *   - Dataplane is unreachable and no cached minimum is known
+ *   - Cached/advertised minimum is not valid semver (warn-only contract per plan)
+ *
+ * @async
+ * @param {string} dataplaneUrl - Dataplane base URL (e.g. `http://localhost:3201`)
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl] - Controller URL for cache lookup/write
+ * @param {boolean} [options.forceRefresh] - Skip cache and probe health now
+ * @returns {Promise<void>}
+ * @throws {Error & { code: 'CLI_VERSION_INCOMPATIBLE', required: string, installed: string, formatted: string }}
+ */
+async function assertDataplaneCliVersionCompatible(dataplaneUrl, options = {}) {
+  if (!dataplaneUrl || typeof dataplaneUrl !== 'string') {
+    return;
+  }
+  const { minBuilderCliVersion } = await resolveMinBuilderCliVersion(
+    options.controllerUrl || null,
+    dataplaneUrl,
+    { forceRefresh: Boolean(options.forceRefresh) }
+  );
+  if (!minBuilderCliVersion) return;
+  if (!isValidSemver(minBuilderCliVersion)) return;
+
+  // Go through module.exports so tests can stub `getInstalledCliVersion`.
+  const installed = module.exports.getInstalledCliVersion();
+  if (!isValidSemver(installed)) return;
+
+  if (compareSemver(installed, minBuilderCliVersion) >= 0) {
+    return;
+  }
+
+  const formatted = formatCliVersionGateError(minBuilderCliVersion, installed);
+  const error = new Error(
+    `Builder CLI ${installed} is below the dataplane minimum (${minBuilderCliVersion}). ` +
+    'Upgrade with: npm install -g @aifabrix/builder@latest'
+  );
+  error.code = ERROR_CODE;
+  error.required = minBuilderCliVersion;
+  error.installed = installed;
+  error.formatted = formatted;
+  throw error;
+}
+
+module.exports = {
+  assertDataplaneCliVersionCompatible,
+  isCliVersionIncompatibleError,
+  getInstalledCliVersion,
+  ERROR_CODE
+};