@aifabrix/builder 2.48.0 → 2.49.1

package/.cursor/skills/README.md

@@ -0,0 +1,14 @@
+# aifabrix-builder Cursor skills
+
+| Skill | Command | Purpose |
+| ----- | ------- | ------- |
+| [builder-push-github](builder-push-github/SKILL.md) | `/push-github` | Release branch CI + optional NPM deploy PR |
+| [builder-repair-release](builder-repair-release/SKILL.md) | `/repair-release` | Version bump + CHANGELOG |
+| [builder-validate-tests](builder-validate-tests/SKILL.md) | `/validate-tests` | Lint + Jest fix loop |
+| [builder-validate-tests-ci](builder-validate-tests-ci/SKILL.md) | `/validate-tests.ci` | `build:ci` / GitHub parity |
+| [builder-validate-code](builder-validate-code/SKILL.md) | `/validate-code` | Code analysis → improvement plans |
+| [builder-validate-plan](builder-validate-plan/SKILL.md) | `/validate-plan` | Pre-implementation plan validation |
+| [builder-validate-implementation](builder-validate-implementation/SKILL.md) | `/validate-implementation` | Post-implementation plan validation |
+| [builder-validate-knowledgebase](builder-validate-knowledgebase/SKILL.md) | `/validate-knowledgebase` | `docs/` + schema validation |
+
+Commands live in `.cursor/commands/`.

package/jest.isolated-projects.js

@@ -60,6 +60,8 @@ const ISOLATED_SUITE_ENTRIES = [
   ['secrets-ensure-catalog-fallback', ['**/tests/lib/core/secrets-ensure-catalog-fallback.test.js']],
   ['secrets-ensure', ['**/tests/lib/core/secrets-ensure.test.js']],
   ['url-declarative-vdir-inactive-env', ['**/tests/lib/utils/url-declarative-vdir-inactive-env.test.js']],
+  ['url-declarative-resolve-load-doc', ['**/tests/lib/utils/url-declarative-resolve-load-doc.test.js']],
+  ['compose-celery-worker', ['**/tests/lib/utils/compose-celery-worker.test.js']],
   [
     'url-declarative-user-cfg-per-app-proxy',
     ['**/tests/lib/utils/url-declarative-user-cfg-per-app-proxy.test.js']
@@ -79,6 +81,7 @@ const ISOLATED_SUITE_ENTRIES = [
   ['infra-kv-discovery', ['**/tests/lib/parameters/infra-kv-discovery.test.js']],
   ['infra-env-defaults', ['**/tests/lib/utils/infra-env-defaults.test.js']],
   ['compose-traefik-template', ['**/tests/lib/infrastructure/compose-traefik-template.test.js']],
+  ['traefik-tls-dynamic', ['**/tests/lib/infrastructure/traefik-tls-dynamic.test.js']],
   ['generator-external-rbac', ['**/tests/lib/generator/generator-external-rbac.test.js']],
   ['helpers-ensure-admin-secrets', ['**/tests/lib/infrastructure/helpers-ensure-admin-secrets.test.js']],
   ['secrets-generator', ['**/tests/lib/utils/secrets-generator.test.js']],

package/jest.projects.js

@@ -156,6 +156,14 @@ const defaultProject = {
       '\\\\tests\\\\lib\\\\utils\\\\url-declarative-vdir-inactive-env.test.js',
       'lib/utils/url-declarative-vdir-inactive-env.test.js',
       'url-declarative-vdir-inactive-env\\.test\\.js',
+      '/tests/lib/utils/url-declarative-resolve-load-doc.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\url-declarative-resolve-load-doc.test.js',
+      'lib/utils/url-declarative-resolve-load-doc.test.js',
+      'url-declarative-resolve-load-doc\\.test\\.js',
+      '/tests/lib/utils/compose-celery-worker.test.js',
+      '\\\\tests\\\\lib\\\\utils\\\\compose-celery-worker.test.js',
+      'lib/utils/compose-celery-worker.test.js',
+      'compose-celery-worker\\.test\\.js',
       '/tests/lib/utils/url-declarative-user-cfg-per-app-proxy.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\url-declarative-user-cfg-per-app-proxy.test.js',
       'lib/utils/url-declarative-user-cfg-per-app-proxy.test.js',
@@ -200,6 +208,10 @@ const defaultProject = {
       '\\\\tests\\\\lib\\\\infrastructure\\\\compose-traefik-template.test.js',
       'lib/infrastructure/compose-traefik-template.test.js',
       'compose-traefik-template\\.test\\.js',
+      '/tests/lib/infrastructure/traefik-tls-dynamic.test.js',
+      '\\\\tests\\\\lib\\\\infrastructure\\\\traefik-tls-dynamic.test.js',
+      'lib/infrastructure/traefik-tls-dynamic.test.js',
+      'traefik-tls-dynamic\\.test\\.js',
       '/tests/lib/utils/paths-app-listing.test.js',
       '\\\\tests\\\\lib\\\\utils\\\\paths-app-listing.test.js',
       'lib/utils/paths-app-listing.test.js',

package/lib/api/applications.api.js

@@ -142,6 +142,28 @@ async function registerApplication(controllerUrl, envKey, authConfig, registrati
   });
 }
 
+/**
+ * Bootstrap application in an environment (install-time, ENCRYPTION_KEY header).
+ * POST /api/v1/environments/{envKey}/applications/bootstrap
+ * @async
+ * @function bootstrapApplication
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {string} encryptionKey - Shared ENCRYPTION_KEY (sent as x-encryption-key; never log)
+ * @param {Object} registrationData - Same body as register
+ * @returns {Promise<Object>} Bootstrap response
+ * @throws {Error} If bootstrap fails
+ */
+async function bootstrapApplication(controllerUrl, envKey, encryptionKey, registrationData) {
+  const client = new ApiClient(controllerUrl, {
+    type: 'bootstrap',
+    encryptionKey
+  });
+  return await client.post(`/api/v1/environments/${envKey}/applications/bootstrap`, {
+    body: registrationData
+  });
+}
+
 /**
  * Rotate application secret
  * POST /api/v1/environments/{envKey}/applications/{appKey}/rotate-secret
@@ -187,6 +209,7 @@ module.exports = {
   updateApplication,
   deleteApplication,
   registerApplication,
+  bootstrapApplication,
   rotateApplicationSecret,
   getApplicationStatus
 };

package/lib/api/dev.api.js

@@ -198,7 +198,7 @@ async function listUsers(serverUrl, clientCertPem, serverCaPem) {
  * @requiresPermission {BuilderServer} Client certificate (X-Client-Cert)
  * @param {string} serverUrl - Builder Server base URL
  * @param {string} clientCertPem - PEM client certificate
- * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | developer | docker)
+ * @param {Object} body - CreateUserDto: developerId, name, email, optional groups (admin | secret-manager | secret-reader | developer | docker)
  * @param {string} [serverCaPem] - Dev root CA PEM
  * @returns {Promise<Object>} UserResponseDto
  */

package/lib/api/index.js

@@ -17,8 +17,9 @@ class ApiClient {
    * App endpoints receive token-only auth (Bearer). x-client-id/x-client-secret are used only for the controller token endpoint.
    * @param {string} baseUrl - Base URL for the API (controller URL)
    * @param {Object} [authConfig] - Authentication configuration
-   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token' | 'client-credentials')
+   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token' | 'client-credentials' | 'bootstrap')
    * @param {string} [authConfig.token] - Bearer token
+   * @param {string} [authConfig.encryptionKey] - Shared ENCRYPTION_KEY (bootstrap only; never log)
    * @param {string} [authConfig.clientId] - Client ID (client-credentials)
    * @param {string} [authConfig.clientSecret] - Client secret (client-credentials)
    */
@@ -79,7 +80,9 @@ class ApiClient {
     }
 
     // User token (bearer) → Authorization: Bearer; application token (client-token) → x-client-token
-    if (this.authConfig.token) {
+    if (this.authConfig.type === 'bootstrap' && this.authConfig.encryptionKey) {
+      headers['x-encryption-key'] = String(this.authConfig.encryptionKey);
+    } else if (this.authConfig.token) {
       if (this.authConfig.type === 'client-token') {
         headers['x-client-token'] = this.authConfig.token;
       } else {

package/lib/api/types/dev.types.js

@@ -31,6 +31,7 @@
  * @property {string} aifabrix-env-config - Env config path
  * @property {string} remote-server - Builder-server base URL
  * @property {string} docker-endpoint - Docker API endpoint
+ * @property {string} [developer-root-domain] - App hostname root (e.g. aifabrix.dev → dev01.aifabrix.dev)
  * @property {boolean} [docker-tls-skip-verify] - When true, Docker uses DOCKER_TLS_VERIFY=0 even if ca.pem exists (client mTLS unchanged)
  * @property {string} sync-ssh-user - SSH user for Mutagen
  * @property {string} sync-ssh-host - SSH host for Mutagen
@@ -45,7 +46,7 @@
  * @property {string} createdAt - ISO 8601
  * @property {boolean} certificateIssued - Whether cert was issued
  * @property {string} [certificateValidNotAfter] - Cert validity end (optional)
- * @property {string[]} groups - Access groups (admin, secret-manager, developer, docker)
+ * @property {string[]} groups - Access groups (admin, secret-manager, secret-reader, developer, docker)
  */
 
 /**
@@ -54,7 +55,7 @@
  * @property {string} developerId - Unique developer ID (numeric string)
  * @property {string} name - Display name
  * @property {string} email - Email
- * @property {string[]} [groups] - Default [developer]; tokens: admin, secret-manager, developer, docker
+ * @property {string[]} [groups] - Default [developer]; tokens: admin, secret-manager, secret-reader, developer, docker
  */
 
 /**

package/lib/app/deploy-config.js

@@ -80,7 +80,8 @@ async function extractDeploymentConfig(options, _variables) {
     repositoryUrl: options.repositoryUrl,
     // Omit default here so deployer can resolve 2s vs 5s from controller deploymentType (GET /api/v1/health)
     pollInterval: Number.isFinite(pollIntervalExplicit) ? pollIntervalExplicit : undefined,
-    pollMaxAttempts: options.pollMaxAttempts || 60
+    pollMaxAttempts: options.pollMaxAttempts || 60,
+    deploymentAuth: options.deploymentAuth
   };
 }
 
@@ -118,7 +119,7 @@ async function configureDeploymentEnvironment(_options, deploymentConfig) {
  * @returns {Promise<void>}
  * @throws {Error} If authentication fails
  */
-async function refreshDeploymentToken(appName, deploymentConfig) {
+async function refreshDeploymentToken(appName, deploymentConfig, options = {}) {
   if (!deploymentConfig.controllerUrl) {
     throw new Error('Controller URL is required. Run "aifabrix login" to set the controller URL in config.yaml');
   }
@@ -127,7 +128,8 @@ async function refreshDeploymentToken(appName, deploymentConfig) {
     const authConfig = await getDeploymentAuth(
       deploymentConfig.controllerUrl,
       deploymentConfig.envKey,
-      appName
+      appName,
+      { deploymentAuth: options.deploymentAuth || deploymentConfig.deploymentAuth }
     );
     if (!authConfig || !authConfig.controller) {
       throw new Error('Invalid authentication configuration: missing controller URL');
@@ -159,7 +161,7 @@ async function loadDeploymentConfig(appName, options) {
   const deploymentConfig = await extractDeploymentConfig(options, variables);
 
   await configureDeploymentEnvironment(options, deploymentConfig);
-  await refreshDeploymentToken(appName, deploymentConfig);
+  await refreshDeploymentToken(appName, deploymentConfig, options);
 
   validateDeploymentConfig(deploymentConfig);
 

package/lib/app/register.js

@@ -199,5 +199,5 @@ async function registerApplication(appKey, options = {}) {
   displayRegistrationResults(responseData, authConfig.apiUrl, environment, registrationData.displayName);
 }
 
-module.exports = { registerApplication, getEnvironmentPrefix };
+module.exports = { registerApplication, getEnvironmentPrefix, buildRegistrationData, saveLocalCredentials, applyLocalhostPortAdjustment };
 

package/lib/app/run-container-start.js

@@ -112,15 +112,6 @@ async function waitForHealthyAndCleanupEnvFiles(appName, port, appConfig, o) {
   logger.log(formatSuccessLine(`Container ${containerName} started`));
   await containerHelpers.logContainerStatus(containerName, debug);
 
-  const healthCheckPath = appConfig?.healthCheck?.path || '/health';
-  const healthUrl = (typeof healthCheck.computeHealthCheckUrl === 'function')
-    ? await healthCheck.computeHealthCheckUrl(appName, port, appConfig, { runOptions: ro })
-    : null;
-  // Keep a stable fallback in the message if URL computation fails for any reason.
-  const displayUrl = (healthUrl && typeof healthUrl === 'string')
-    ? healthUrl
-    : `http://localhost:${port}${healthCheckPath}`;
-  logger.log(formatProgress(`Waiting for healthy: ${displayUrl}…`));
   await healthCheck.waitForHealthCheck(appName, 90, port, appConfig, debug, ro);
 
   for (const p of [runEnvPath, runEnvAdminPath]) {

package/lib/app/run-helpers.js

@@ -290,8 +290,10 @@ function calculateComposePort(options, appConfig, developerId) {
  * @param {string} devDir - Dev directory path
  * @returns {Promise<string>} Path to compose file
  */
-async function generateComposeFile(appName, appConfig, composeOptions, devDir) {
-  logger.log(formatProgress('Generating Docker Compose configuration…'));
+async function generateComposeFile(appName, appConfig, composeOptions, devDir, logOpts = {}) {
+  if (!logOpts.suppressProgressLog) {
+    logger.log(formatProgress('Generating Docker Compose configuration…'));
+  }
   const composeContent = await composeGenerator.generateDockerCompose(appName, appConfig, composeOptions);
   runEnvCompose.assertNoPasswordLiteralsInCompose(composeContent);
   const tempComposePath = path.join(devDir, 'docker-compose.yaml');
@@ -352,7 +354,7 @@ async function prepareEnvironment(appName, appConfig, options) {
   );
 
   runEnvCompose.cleanApplicationsDir(developerId);
-  logger.log(formatProgress('Building merged .env (admin + app secrets)…'));
+  logger.log(formatProgress('Preparing run environment (env + compose)…'));
   const { runEnvPath, runEnvAdminPath } = await runEnvCompose.buildMergedRunEnvAndWrite(
     appName,
     appConfig,
@@ -370,7 +372,9 @@ async function prepareEnvironment(appName, appConfig, options) {
     omitAppTraefikLabels: userCfg.traefik === false
   };
   composeOptions.port = calculateComposePort(composeOptions, appConfig, developerId);
-  const composePath = await generateComposeFile(appName, appConfig, composeOptions, devDir);
+  const composePath = await generateComposeFile(appName, appConfig, composeOptions, devDir, {
+    suppressProgressLog: true
+  });
 
   await writeEnvOutputIfConfigured(appName, appConfig, runEnvPath, options);
 

package/lib/app/run-reload-sync.js

@@ -9,16 +9,15 @@
 'use strict';
 
 const chalk = require('chalk');
-const { formatProgress } = require('../utils/cli-test-layout-chalk');
+const { formatProgress, metadata } = require('../utils/cli-test-layout-chalk');
 const config = require('../core/config');
 const logger = require('../utils/logger');
 const mutagen = require('../utils/mutagen');
 const pathsUtil = require('../utils/paths');
 const {
   isReloadBindMountOnEngineHost,
-  isLocalhostSyncSshHost
+  isHostOnThisMachine
 } = require('../utils/docker-reload-mount');
-const { sectionTitle, headerKeyValue, metadata } = require('../utils/cli-test-layout-chalk');
 
 /**
  * @typedef {Object} ReloadSyncSummaryBind
@@ -109,9 +108,11 @@ async function ensureReloadSync(appName, developerId, debug, codePath, remoteSyn
     return { transport: 'bind-mount', hostPath: codePath };
   }
   const syncSshHost = await config.getSyncSshHost();
-  if (isLocalhostSyncSshHost(syncSshHost || '')) {
+  if (isHostOnThisMachine(syncSshHost || '')) {
     if (debug) {
-      logger.log(chalk.gray('[DEBUG] sync-ssh-host is localhost; skipping Mutagen, using local path'));
+      logger.log(
+        chalk.gray('[DEBUG] sync-ssh-host is this machine; skipping Mutagen, using local path')
+      );
     }
     return { transport: 'bind-mount', hostPath: codePath };
   }
@@ -127,22 +128,19 @@ function logReloadDevSummary(reload, summary) {
   if (!reload || !summary) {
     return;
   }
-  logger.log('');
-  logger.log(sectionTitle('Reload (dev)'));
   if (summary.transport === 'bind-mount') {
-    logger.log(headerKeyValue('Transport:', 'Direct bind mount on the Docker host (no Mutagen).'));
-    logger.log(headerKeyValue('Host path → container:', `${summary.hostPath} → /app`));
-    logger.log(metadata('Edits under the host path are visible inside the container immediately.'));
-    logger.log('');
+    logger.log(
+      metadata(
+        'Reload (dev) — Edits under the host path are visible inside the container immediately.'
+      )
+    );
     return;
   }
-  logger.log(headerKeyValue('Transport:', 'Mutagen two-way sync (Docker engine on another host).'));
-  logger.log(headerKeyValue('Session:', summary.sessionName));
-  logger.log(headerKeyValue('Sync host:', summary.syncSshHost));
-  logger.log(headerKeyValue('Local folder:', summary.localPath));
-  logger.log(headerKeyValue('Remote mount (-v):', summary.remotePath));
-  logger.log(metadata(`Mutagen endpoint: ${summary.sshUrl}`));
-  logger.log('');
+  logger.log(
+    metadata(
+      `Reload (dev) — Mutagen sync (${summary.sessionName}); edits sync to ${summary.remotePath} before the container sees them.`
+    )
+  );
 }
 
 module.exports = { ensureReloadSync, logReloadDevSummary };

package/lib/app/run-stop-containers.js

@@ -8,7 +8,10 @@
 
 'use strict';
 
-const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const {
+  formatProgress,
+  formatSuccessLine
+} = require('../utils/cli-test-layout-chalk');
 const config = require('../core/config');
 const logger = require('../utils/logger');
 const containerHelpers = require('../utils/app-run-containers');
@@ -16,6 +19,34 @@ const helpers = require('./run-helpers');
 const { computeEffectiveEnvironmentScopedResources } = require('../utils/environment-scoped-resources');
 const { getCeleryCompanionAppKeys } = require('../utils/celery-companion-apps');
 
+function shouldUseReplaceContainerSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {string} progressText
+ * @param {string} successText
+ * @param {() => Promise<void>} work
+ * @returns {Promise<void>}
+ */
+async function runContainerReplaceLine(progressText, successText, work) {
+  if (shouldUseReplaceContainerSpinner()) {
+    const ora = require('ora');
+    const spinner = ora({ text: progressText, spinner: 'dots' }).start();
+    try {
+      await work();
+      spinner.succeed(successText);
+    } catch (error) {
+      spinner.fail(progressText.replace(/…$/, '').trim());
+      throw error;
+    }
+    return;
+  }
+  logger.log(formatProgress(progressText));
+  await work();
+  logger.log(formatSuccessLine(successText));
+}
+
 /**
  * @param {Object} appConfig
  * @param {Object} options
@@ -62,8 +93,14 @@ async function findRunningCompanionKeys(companionKeys, developerId, debug, scope
 async function stopCompanionContainers(companionKeys, developerId, debug, scopeOpts) {
   for (const companionKey of companionKeys) {
     const companionName = containerHelpers.getContainerName(companionKey, developerId, scopeOpts);
-    logger.log(formatWarningLine(`Stopping companion container ${companionName}`));
-    await helpers.stopAndRemoveContainer(companionKey, developerId, debug, scopeOpts);
+    await runContainerReplaceLine(
+      `Stopping companion container ${companionName}…`,
+      `Companion container ${companionName} stopped and removed`,
+      () =>
+        helpers.stopAndRemoveContainer(companionKey, developerId, debug, scopeOpts, {
+          suppressLog: true
+        })
+    );
   }
 }
 
@@ -101,8 +138,14 @@ async function checkAndStopContainer(appName, appConfig, options, debug) {
     return;
   }
   const containerName = containerHelpers.getContainerName(appName, developerId, scopeOpts);
-  logger.log(formatWarningLine(`Container ${containerName} is already running`));
-  await helpers.stopAndRemoveContainer(appName, developerId, debug, scopeOpts);
+  await runContainerReplaceLine(
+    `Replacing running container ${containerName}…`,
+    `Container ${containerName} stopped and removed`,
+    () =>
+      helpers.stopAndRemoveContainer(appName, developerId, debug, scopeOpts, {
+        suppressLog: true
+      })
+  );
 }
 
 module.exports = {

package/lib/app/run.js

@@ -29,7 +29,7 @@ const { ensureReloadSync, logReloadDevSummary } = require('./run-reload-sync');
 const { logRestartDevMountSummary } = require('./restart-display');
 const { checkAndStopContainer } = require('./run-stop-containers');
 const { execWithDockerEnv } = require('../utils/docker-exec');
-const { isRunCliNoProxy } = require('../utils/run-cli-flags');
+const { resolveRunProxyPersistEnabled, resolveRunEffectiveNoProxy } = require('../utils/run-cli-flags');
 
 /**
  * True if host is localhost or 127.0.0.1 (case-insensitive).
@@ -347,7 +347,10 @@ async function prepareAppRun(appName, options, debug) {
   }
   let userCfg = await config.getConfig();
   const appsDefaults = require('../utils/applications-config-defaults');
-  await appsDefaults.persistApplicationRunProxyFlag(appName, !isRunCliNoProxy(options));
+  await appsDefaults.persistApplicationRunProxyFlag(
+    appName,
+    resolveRunProxyPersistEnabled(options, userCfg)
+  );
   if (envKey === 'dev') {
     await appsDefaults.persistApplicationReloadFlag(appName, options.reload === true);
   }
@@ -356,7 +359,7 @@ async function prepareAppRun(appName, options, debug) {
   const mergedOpts = {
     ...options,
     reload: options.reload === true,
-    noProxy: isRunCliNoProxy(options) || !savedProxyHint
+    noProxy: resolveRunEffectiveNoProxy(options, userCfg, savedProxyHint)
   };
   logger.log('');
   logger.log(sectionTitle('Run'));

package/lib/app/show.js

@@ -45,11 +45,11 @@ const {
  * @param {Object} userCfg
  */
 function attachRunDefaultsFromUserConfig(summary, appKey, userCfg) {
-  const { isApplicationsReloadDefaultOn, getApplicationsRunProxyHint } = require('../utils/applications-config-defaults');
+  const { isApplicationsReloadDefaultOn, getEffectiveApplicationsRunProxyHint } = require('../utils/applications-config-defaults');
   if (isApplicationsReloadDefaultOn(userCfg, appKey)) {
     summary.runReloadDefault = true;
   }
-  summary.runProxyDefault = getApplicationsRunProxyHint(userCfg, appKey);
+  summary.runProxyDefault = getEffectiveApplicationsRunProxyHint(userCfg, appKey);
 }
 
 /**

package/lib/cli/infra-guided-auth.js

@@ -16,6 +16,7 @@ const { withMutedLogger } = require('../utils/with-muted-logger');
 const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 const { isAuthenticationError } = require('../utils/cli-utils');
 const { resolveControllerUrl, isPlatformAuthValidForController } = require('../utils/controller-url');
+const { canUseBootstrapProvision } = require('../commands/up-dataplane-bootstrap');
 
 /**
  * @param {Object} authOpts
@@ -59,7 +60,10 @@ async function runGuidedDeviceLogin(handleLoginFn, controllerUrl, opts = {}) {
     compact: true,
     skipControllerUrlPersist: Boolean(opts.tokenControllerUrl),
     skipDataplaneVersionRefresh: opts.skipDataplaneVersionRefresh === true,
-    exitOnFailure: false
+    exitOnFailure: false,
+    guidedInstall: opts.guidedInstall === true,
+    onProgressText: opts.onProgressText,
+    suppressSuccessLine: opts.suppressSuccessLine === true
   });
 }
 
@@ -74,12 +78,17 @@ async function runGuidedAuthStep(handleLoginFn, authOpts, spinners) {
   const spin = spinners.startSpinner('Authenticating...');
   const { apiUrl, tokenUrl } = await resolveGuidedAuthControllerUrls(authOpts);
   const loginOpts = { skipDataplaneVersionRefresh: true, tokenControllerUrl: tokenUrl };
+  const bootstrapEligible = await canUseBootstrapProvision({ skipInfraCheck: true });
   const skipLogin =
+    bootstrapEligible ||
     authOpts.skipLoginIfAuthenticated === true ||
     (await isPlatformAuthValidForController(tokenUrl));
   try {
     if (skipLogin) {
-      spinners.stopSpinnerSuccess(spin, 'Already authenticated');
+      spinners.stopSpinnerSuccess(
+        spin,
+        bootstrapEligible ? 'Bootstrap provision (no device login)' : 'Already authenticated'
+      );
       return;
     }
     await runGuidedDeviceLogin(handleLoginFn, apiUrl, loginOpts);
@@ -103,24 +112,53 @@ async function runGuidedAuthStep(handleLoginFn, authOpts, spinners) {
  * @param {Function} handleUpDataplane
  * @param {Function} handleLoginFn
  * @param {string} controllerUrl
+ * @param {{ onSpinnerText?: (text: string) => void }} [ui]
  * @returns {Promise<void>}
  */
-async function runGuidedDataplaneWithAuthRecovery(options, handleUpDataplane, handleLoginFn, controllerUrl) {
+async function runGuidedDataplaneWithAuthRecovery(
+  options,
+  handleUpDataplane,
+  handleLoginFn,
+  controllerUrl,
+  ui = {}
+) {
+  const onSpinnerText = typeof ui.onSpinnerText === 'function' ? ui.onSpinnerText : null;
+  const dataplaneOpts = {
+    ...options,
+    platformInstall: true,
+    skipInfraCheck: true,
+    ...(onSpinnerText ? { onPollText: onSpinnerText } : {})
+  };
   try {
-    await withMutedLogger(() =>
-      handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
-    );
+    await withMutedLogger(() => handleUpDataplane(dataplaneOpts));
   } catch (error) {
     if (!isAuthenticationError(error)) {
       throw error;
     }
+    const bootstrapEligible = await canUseBootstrapProvision({
+      skipInfraCheck: true,
+      allowNonDev: options.allowNonDev
+    });
+    if (bootstrapEligible) {
+      throw error;
+    }
     const loginUrl = error.controllerUrl || controllerUrl || (await resolveControllerUrl());
-    logger.log('');
-    logger.log(chalk.yellow('Device login required to register and deploy Dataplane.'));
-    await runGuidedDeviceLogin(handleLoginFn, loginUrl, { skipDataplaneVersionRefresh: false });
-    await withMutedLogger(() =>
-      handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
-    );
+    if (onSpinnerText) {
+      onSpinnerText('Authenticating...');
+    } else {
+      logger.log('');
+      logger.log(chalk.yellow('Device login required to register and deploy Dataplane.'));
+    }
+    await runGuidedDeviceLogin(handleLoginFn, loginUrl, {
+      skipDataplaneVersionRefresh: false,
+      compact: true,
+      guidedInstall: true,
+      onProgressText: onSpinnerText || undefined
+    });
+    if (onSpinnerText) {
+      onSpinnerText('Validating Dataplane...');
+    }
+    await withMutedLogger(() => handleUpDataplane(dataplaneOpts));
   }
 }