@aifabrix/builder 2.45.0 → 2.46.0

package/lib/utils/app-relative-path-env.js

@@ -0,0 +1,112 @@
+/**
+ * Per-app virtual-directory env var names ({@code <NAME>_RELATIVE_PATH}) for Builder CLI.
+ *
+ * @fileoverview {@code app.key} → {@code DATAPLANE_RELATIVE_PATH}, {@code MYAPP_RELATIVE_PATH}, etc.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** Must match {@link module:lib/utils/url-declarative-vdir-inactive-env} token (avoid circular require). */
+const URL_DECLARATIVE_VDIR_PUBLIC_TOKEN = 'url://vdir-public';
+
+/** Suffix for runtime mount vars derived from {@code application.yaml} {@code app.key}. */
+const APP_RELATIVE_PATH_ENV_SUFFIX = '_RELATIVE_PATH';
+
+/**
+ * Apps whose runtime vdir env name is not {@code UPPER(appKey)_RELATIVE_PATH}.
+ * @type {Readonly<Record<string, string>>}
+ */
+const APP_RELATIVE_PATH_ENV_KEY_OVERRIDES = Object.freeze({
+  keycloak: 'KC_HTTP_RELATIVE_PATH',
+  'miso-controller': 'MISO_RELATIVE_PATH'
+});
+
+/** Always rewritten to "/" when front-door path is inactive (shared infra apps). */
+const INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS = Object.freeze([
+  'KC_HTTP_RELATIVE_PATH',
+  'MISO_RELATIVE_PATH'
+]);
+
+/**
+ * @param {string} appKey - {@code application.yaml} {@code app.key}
+ * @returns {string} e.g. {@code dataplane} → {@code DATAPLANE_RELATIVE_PATH}, {@code myapp} → {@code MYAPP_RELATIVE_PATH}
+ */
+function appKeyToRelativePathEnvKey(appKey) {
+  const key = String(appKey || '').trim();
+  if (!key) {
+    return '';
+  }
+  const override = APP_RELATIVE_PATH_ENV_KEY_OVERRIDES[key];
+  if (override) {
+    return override;
+  }
+  const upper = key.replace(/-/g, '_').toUpperCase();
+  return `${upper}${APP_RELATIVE_PATH_ENV_SUFFIX}`;
+}
+
+/**
+ * Whether {@code key} is a runtime vdir env name (static Keycloak/Miso or {@code NAME_RELATIVE_PATH}).
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isAppRelativePathEnvKey(key) {
+  const name = String(key || '').trim();
+  if (!name) {
+    return false;
+  }
+  if (INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS.includes(name)) {
+    return true;
+  }
+  return name.endsWith(APP_RELATIVE_PATH_ENV_SUFFIX);
+}
+
+/**
+ * Env keys to rewrite when path is inactive: static Keycloak/Miso + current app vdir key.
+ * @param {string|null|undefined} appKey - {@code application.yaml} {@code app.key}
+ * @returns {ReadonlySet<string>}
+ */
+function resolveInactiveVdirRewriteEnvKeys(appKey) {
+  const keys = new Set(INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS);
+  const envKey = appKeyToRelativePathEnvKey(appKey);
+  if (envKey) {
+    keys.add(envKey);
+  }
+  return keys;
+}
+
+/**
+ * When an app is created from a product template, rename the template's {@code *_RELATIVE_PATH}
+ * line to match {@code app.key} (e.g. {@code DATAPLANE_RELATIVE_PATH} → {@code MYAPP_RELATIVE_PATH}).
+ * @param {string} content - {@code env.template} body
+ * @param {string} appKey
+ * @returns {string}
+ */
+function renameAppRelativePathEnvKeyInTemplate(content, appKey) {
+  const targetKey = appKeyToRelativePathEnvKey(appKey);
+  if (!targetKey || !content || !content.includes(URL_DECLARATIVE_VDIR_PUBLIC_TOKEN)) {
+    return content;
+  }
+  const escapedToken = URL_DECLARATIVE_VDIR_PUBLIC_TOKEN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const lineRe = new RegExp(
+    `^([ \\t]*)([A-Z][A-Z0-9_]*${APP_RELATIVE_PATH_ENV_SUFFIX})([ \\t]*=\\s*)${escapedToken}[ \\t]*$`,
+    'gm'
+  );
+  return content.replace(lineRe, (match, indent, currentKey, eq) => {
+    if (currentKey === targetKey) {
+      return match;
+    }
+    return `${indent}${targetKey}${eq}${URL_DECLARATIVE_VDIR_PUBLIC_TOKEN}`;
+  });
+}
+
+module.exports = {
+  APP_RELATIVE_PATH_ENV_SUFFIX,
+  APP_RELATIVE_PATH_ENV_KEY_OVERRIDES,
+  INACTIVE_VDIR_PUBLIC_STATIC_ENV_KEYS,
+  appKeyToRelativePathEnvKey,
+  isAppRelativePathEnvKey,
+  resolveInactiveVdirRewriteEnvKeys,
+  renameAppRelativePathEnvKeyInTemplate
+};

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-secrets-error-format.js

@@ -8,6 +8,7 @@
 
 const chalk = require('chalk');
 const { metadata, sectionTitle } = require('./cli-layout-chalk');
+const { kvRefToSecretSetKey } = require('./secrets-missing-error');
 
 /**
  * @param {string[]} messages - Output lines
@@ -25,34 +26,72 @@ function pushMissingSecretsBodyLines(messages, missingSecretsMatch) {
       for (const ref of parts) {
         messages.push(`   ${chalk.cyan('-')} ${chalk.white(ref)}`);
       }
-      return;
+      return parts;
     }
     if (parts.length === 1) {
       messages.push(`   ${sectionTitle('Missing secrets:')} ${chalk.white(parts[0])}`);
-      return;
+      return parts;
     }
     messages.push(`   ${sectionTitle('Missing secrets:')}`);
-    return;
+    return [];
   }
   messages.push(`   ${chalk.white('Missing secrets in secrets file.')}`);
+  return [];
 }
 
 /**
- * @param {string[]} messages - Output lines
- * @param {RegExpMatchArray|null} fileInfoMatch - File location capture
- * @param {RegExpMatchArray|null} resolveMatch - Resolve command capture
+ * @param {string} errorMsg
+ * @returns {Map<string, string>}
+ */
+function parseEnvTemplateLineHints(errorMsg) {
+  const map = new Map();
+  const re = /^Env-template-line: (kv:\/\/[^\s|]+)\|(.+)$/gm;
+  let m;
+  while ((m = re.exec(errorMsg)) !== null) {
+    map.set(m[1].trim(), m[2].trim());
+  }
+  return map;
+}
+
+/**
+ * @param {string[]} messages
+ * @param {string[]} missingRefs
+ * @param {Map<string, string>} templateLinesByRef
+ * @param {string|null} envTemplatePath
  */
-function pushSecretsResolutionHintLines(messages, fileInfoMatch, resolveMatch) {
+function pushRemediationHintLines(messages, missingRefs, templateLinesByRef, envTemplatePath) {
+  messages.push(`   ${sectionTitle('You can fix this two ways:')}`);
+  messages.push(
+    `   ${chalk.cyan('1.')} ${chalk.white('Not used by your external system?')} Comment out or delete the line in env.template.`
+  );
+  if (envTemplatePath) {
+    messages.push(`   ${metadata('env.template:')} ${chalk.white(envTemplatePath)}`);
+  }
+  for (const ref of missingRefs) {
+    const line = templateLinesByRef.get(ref);
+    if (line) {
+      messages.push(`   ${metadata('Comment or delete:')} ${chalk.gray(line)}`);
+    }
+  }
+  messages.push(
+    `   ${chalk.cyan('2.')} ${chalk.white('Store the value:')} ${metadata('aifabrix secret set')} ${chalk.yellow('<key>')} ${chalk.gray('"<your-value>"')}`
+  );
+  for (const ref of missingRefs) {
+    const key = kvRefToSecretSetKey(ref);
+    if (key) {
+      messages.push(`   ${metadata('Example:')} ${chalk.yellow(`aifabrix secret set ${key} "<your-value>"`)}`);
+    }
+  }
+}
+
+/**
+ * @param {string[]} messages
+ * @param {RegExpMatchArray|null} fileInfoMatch
+ */
+function pushSecretsFileLocationLine(messages, fileInfoMatch) {
   if (fileInfoMatch) {
     messages.push(`   ${metadata('Secrets file location:')} ${chalk.white(fileInfoMatch[1])}`);
   }
-  if (resolveMatch) {
-    messages.push(
-      `   ${metadata('Run:')} ${chalk.yellow(`aifabrix resolve ${resolveMatch[1]} to generate missing secrets.`)}`
-    );
-    return;
-  }
-  messages.push(`   ${metadata('Run:')} ${chalk.yellow('aifabrix resolve <app-name> to generate missing secrets.')}`);
 }
 
 /**
@@ -66,13 +105,36 @@ function formatSecretsError(errorMsg) {
   }
 
   const messages = [];
-  pushMissingSecretsBodyLines(messages, errorMsg.match(/Missing secrets: ([^\n]+)/));
-  pushSecretsResolutionHintLines(
-    messages,
-    errorMsg.match(/Secrets file location: ([^\n]+)/),
-    errorMsg.match(/Run "aifabrix resolve ([^"]+)"/)
-  );
+  const missingRefs = pushMissingSecretsBodyLines(messages, errorMsg.match(/Missing secrets: ([^\n]+)/));
+  pushSecretsFileLocationLine(messages, errorMsg.match(/Secrets file location: ([^\n]+)/));
+  const envTemplatePathMatch = errorMsg.match(/Env-template-path: ([^\n]+)/);
+  const envTemplatePath = envTemplatePathMatch ? envTemplatePathMatch[1].trim() : null;
+  const templateLinesByRef = parseEnvTemplateLineHints(errorMsg);
+  const refs =
+    missingRefs.length > 0
+      ? missingRefs
+      : [...templateLinesByRef.keys()];
+  if (refs.length > 0) {
+    pushRemediationHintLines(messages, refs, templateLinesByRef, envTemplatePath);
+  }
+  const staleMatch = errorMsg.match(/Stale-template-hint: oauth-leftover \| repair ([^\n]+)/);
+  if (staleMatch) {
+    messages.push(
+      `   ${chalk.yellow('⚠')} ${chalk.white('These keys are often left over after switching to apikey/bearerToken auth.')}`
+    );
+    messages.push(
+      `   ${metadata('Run:')} ${chalk.yellow(`aifabrix repair ${staleMatch[1].trim()}`)} ${chalk.gray('to comment stale OAuth lines in env.template')}`
+    );
+  }
   return messages;
 }
 
-module.exports = { formatSecretsError };
+/**
+ * @param {string} errorMsg
+ * @returns {boolean}
+ */
+function isMissingSecretsErrorMessage(errorMsg) {
+  return typeof errorMsg === 'string' && errorMsg.includes('Missing secrets');
+}
+
+module.exports = { formatSecretsError, isMissingSecretsErrorMessage };

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/cli-utils.js

@@ -12,7 +12,7 @@ const path = require('path');
 const chalk = require('chalk');
 const logger = require('./logger');
 const { formatBlockingError, infoLine } = require('./cli-layout-chalk');
-const { formatSecretsError } = require('./cli-secrets-error-format');
+const { formatSecretsError, isMissingSecretsErrorMessage } = require('./cli-secrets-error-format');
 const { getDockerDaemonStartHintSentence, getDockerApiOverTcpHintLines } = require('./docker-not-running-hint');
 
 /**
@@ -337,6 +337,15 @@ function formatError(error) {
     return formatFormattedError(error.formatted);
   }
 
+  if (error.network === true) {
+    const { formatNetworkError } = require('./api-error-handler');
+    const formatted = formatNetworkError(error.message || 'Network error', {
+      endpointUrl: error.endpointUrl,
+      serviceLabel: error.serviceLabel || 'service'
+    });
+    return formatFormattedError(formatted);
+  }
+
   const errorMsg = error.message || '';
 
   // Try different error formatters in order of specificity
@@ -355,10 +364,12 @@ function formatError(error) {
  * @param {string} command - Command that failed
  * @param {string[]} errorMessages - Error message lines
  */
-function logError(command, errorMessages) {
+function logError(command, errorMessages, options = {}) {
   logger.error(`\n${formatBlockingError(`Error in ${command} command:`)}`);
   errorMessages.forEach(msg => logger.error(msg));
-  logger.log(`\n${infoLine('ℹ Run "aifabrix doctor" for environment diagnostics.')}\n`);
+  if (!options.skipDoctor) {
+    logger.log(`\n${infoLine('ℹ Run "aifabrix doctor" for environment diagnostics.')}\n`);
+  }
 }
 
 /**
@@ -396,7 +407,8 @@ function isAuthenticationError(error) {
  */
 function handleCommandError(error, command) {
   const errorMessages = formatError(error);
-  logError(command, errorMessages);
+  const skipDoctor = isMissingSecretsErrorMessage(error && error.message);
+  logError(command, errorMessages, { skipDoctor });
   if (error.wizardResumeMessage) {
     logger.log(error.wizardResumeMessage);
   }

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

@@ -61,6 +61,10 @@ function normalizePythonReloadForComposeMounted(raw) {
   if (/^python3?\s+-m\s+uvicorn\s+/i.test(s)) {
     return s;
   }
+  const envPrefixed = s.match(/^((?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*)(uvicorn\s+.*)$/);
+  if (envPrefixed) {
+    return `${envPrefixed[1]}python -m uvicorn ${envPrefixed[2].slice('uvicorn '.length)}`;
+  }
   if (s.startsWith('uvicorn ')) {
     return `python -m uvicorn ${s.slice('uvicorn '.length)}`;
   }

package/lib/utils/compose-traefik-ingress-base.js

@@ -86,6 +86,19 @@ function expandFrontDoorHostPlaceholders(template, developerIdRaw, remoteServer)
   return t;
 }
 
+function templateUsesRemoteHostPlaceholder(hostTemplate) {
+  return /\$\{REMOTE_HOST\}/.test(String(hostTemplate || ''));
+}
+
+function resolveTraefikRouterHost(hostTemplate, developerIdRaw, remoteServer) {
+  const usesRemote = templateUsesRemoteHostPlaceholder(hostTemplate);
+  const hasRemote = Boolean(remoteServer && String(remoteServer).trim());
+  if (usesRemote && !hasRemote) {
+    return 'localhost';
+  }
+  return expandFrontDoorHostPlaceholders(hostTemplate, developerIdRaw, remoteServer);
+}
+
 /**
  * Traefik PathPrefix / host / TLS from frontDoorRouting (public ingress). Does not include StripPrefix — that follows
  * the in-container health path: private URL is `http://<service>:<port>` plus the probe path; `/dev`, `/tst`, `/auth`,
@@ -105,7 +118,7 @@ function buildTraefikIngressBase(config, devId, scopeOpts, remoteServer) {
   if (!frontDoor.host || typeof frontDoor.host !== 'string') {
     throw new Error('frontDoorRouting.host is required when frontDoorRouting.enabled is true');
   }
-  const host = expandFrontDoorHostPlaceholders(frontDoor.host, devId, remoteServer);
+  const host = resolveTraefikRouterHost(frontDoor.host, devId, remoteServer);
   const basePath = derivePathFromPattern(frontDoor.pattern);
   let pathOut = basePath;
   if (
@@ -153,6 +166,8 @@ module.exports = {
   resolveTraefikTlsEnabled,
   buildDevUsernameForFrontDoorHost,
   expandFrontDoorHostPlaceholders,
+  templateUsesRemoteHostPlaceholder,
+  resolveTraefikRouterHost,
   buildTraefikIngressBase,
   computeTraefikStripPathPrefix
 };

package/lib/utils/config-secrets-path.js

@@ -0,0 +1,46 @@
+/**
+ * Secrets path config helpers.
+ *
+ * @fileoverview Keeps lib/core/config.js under max-lines
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Expand leading ~ to home directory so config paths like ~/.aifabrix/secrets.local.yaml resolve correctly.
+ * @param {string} filePath - Path that may start with ~ or ~/
+ * @returns {string} Path with ~ expanded, or unchanged if no leading ~
+ */
+function expandTilde(filePath) {
+  if (!filePath || typeof filePath !== 'string') return filePath;
+  if (filePath === '~') return os.homedir();
+  if (filePath.startsWith('~/') || filePath.startsWith('~' + path.sep)) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+function createSecretsPathFunctions(getConfig, saveConfig) {
+  async function getSecretsPath() {
+    const cfg = await getConfig();
+    const raw = cfg['aifabrix-secrets'] || cfg['secrets-path'] || null;
+    return raw ? expandTilde(raw) : null;
+  }
+
+  async function setSecretsPath(secretsPath) {
+    if (typeof secretsPath !== 'string') {
+      throw new Error('Secrets path is required and must be a string');
+    }
+    const cfg = await getConfig();
+    cfg['aifabrix-secrets'] = secretsPath.trim() || undefined;
+    await saveConfig(cfg);
+  }
+
+  return { getSecretsPath, setSecretsPath };
+}
+
+module.exports = { createSecretsPathFunctions };
+

package/lib/utils/controller-url.js

@@ -12,6 +12,7 @@
 const { getDeveloperIdNumber } = require('./env-map');
 const devConfig = require('./dev-config');
 const config = require('../core/config');
+const { getDeviceToken, isTokenExpired } = require('./token-manager');
 
 /**
  * Calculate default controller URL based on developer ID
@@ -40,7 +41,6 @@ function normalizeUrl(url) {
   }
   return url.trim().replace(/\/+$/, '');
 }
-
 /**
  * True when `config.yaml` has a non-expired-looking device entry for this controller URL
  * (normalized host/path comparison).
@@ -68,6 +68,90 @@ async function hasStoredDeviceTokenForController(controllerUrl) {
   }
 }
 
+/**
+ * True when a stored, non-expired device token exists (local config only — no refresh HTTP).
+ * Setup uses this to decide whether to skip the device-login step; avoids refresh warnings
+ * when the controller is not up yet or `device:` is empty.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<boolean>}
+ */
+async function isDeviceTokenUsableForController(controllerUrl) {
+  if (!(await hasStoredDeviceTokenForController(controllerUrl))) {
+    return false;
+  }
+  const want = normalizeUrl(controllerUrl);
+  try {
+    const tokenInfo = await getDeviceToken(want);
+    return Boolean(tokenInfo && tokenInfo.token && !isTokenExpired(tokenInfo.expiresAt));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when a stored device token can be refreshed (if needed) and validated against the controller API.
+ * Prefer this after the controller is reachable (guided platform auth step). Falls back to local expiry-only
+ * check when the controller is not reachable yet.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<boolean>}
+ */
+async function isPlatformAuthValidForController(controllerUrl) {
+  if (!(await hasStoredDeviceTokenForController(controllerUrl))) {
+    return false;
+  }
+  const want = normalizeUrl(controllerUrl);
+
+  if (!(await isControllerHealthReachable(want))) {
+    return isDeviceTokenUsableForController(controllerUrl);
+  }
+
+  const { getOrRefreshDeviceToken } = require('./token-manager');
+  const { getAuthUser } = require('../api/auth.api');
+
+  let tokenResult = null;
+  try {
+    tokenResult = await getOrRefreshDeviceToken(want);
+  } catch {
+    tokenResult = null;
+  }
+
+  if (!tokenResult || !tokenResult.token) {
+    return false;
+  }
+
+  try {
+    const response = await getAuthUser(want, { type: 'bearer', token: tokenResult.token });
+    return Boolean(response.success && response.data && response.data.authenticated !== false);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Best-effort GET /health on the controller (no auth). Used to avoid token refresh HTTP
+ * during setup before Miso Controller is running.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<boolean>}
+ */
+async function isControllerHealthReachable(controllerUrl) {
+  const base = normalizeUrl(controllerUrl);
+  if (!base) {
+    return false;
+  }
+  try {
+    const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(2500) });
+    return res.ok;
+  } 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
@@ -152,6 +236,9 @@ async function resolveControllerUrl() {
 module.exports = {
   getDefaultControllerUrl,
   hasStoredDeviceTokenForController,
+  isDeviceTokenUsableForController,
+  isPlatformAuthValidForController,
+  isControllerHealthReachable,
   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
+};