@aifabrix/builder 2.55.0 → 2.55.2

package/lib/schema/type/document-storage.json

@@ -282,7 +282,7 @@
         },
         "fieldHints": {
           "type": "object",
-          "description": "Optional per-field extraction hints for governed FK review (plan 441.1).",
+          "description": "Optional per-field guidance for AI metadata extraction and governed FK review.",
           "additionalProperties": {
             "type": "string",
             "minLength": 1,

package/lib/utils/api-required-permissions.js

@@ -0,0 +1,271 @@
+/**
+ * Resolve required RBAC scopes for online API calls.
+ *
+ * Catalog is built from `@requiresPermission` plus the HTTP path in `lib/api/*.api.js`.
+ * Used when a 403 body does not list missing/required permissions.
+ *
+ * @fileoverview Fallback required-permission lookup for 403 errors
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fsRealSync = require('../internal/fs-real-sync');
+const path = require('path');
+
+const SCOPE_IN_TEXT_RE = /\b[a-z][a-z0-9_-]*:[a-z][a-z0-9_-]*(?::[a-z][a-z0-9_-]*)*\b/gi;
+const SKIP_SCOPE_SCHEMES = new Set(['http', 'https', 'mailto', 'ws', 'wss']);
+
+/** @type {Array<{ method: string, regex: RegExp, service: string, permissions: string[] }>|null} */
+let cachedCatalog = null;
+
+/**
+ * CLI command name (handleCommandError second arg) → required permission fallback.
+ * URL catalog is preferred; this is used when the 403 has no request URL.
+ */
+const COMMAND_REQUIRED_PERMISSIONS = Object.freeze({
+  deploy: { service: 'Controller', permissions: ['applications:deploy'] },
+  'env deploy': { service: 'Controller', permissions: ['controller:deploy'] },
+  upload: { service: 'Dataplane', permissions: ['external-system:publish'] },
+  download: { service: 'Dataplane', permissions: ['external-system:read'] },
+  delete: { service: 'Dataplane', permissions: ['external-system:delete'] },
+  wizard: { service: 'Dataplane', permissions: ['external-system:create'] },
+  'credential list': { service: 'Dataplane', permissions: ['credential:read'] },
+  'deployment list': { service: 'Controller', permissions: ['deployments:read'] },
+  'app register': { service: 'Controller', permissions: ['environments-applications:create'] },
+  'app list': { service: 'Controller', permissions: ['environments-applications:read'] }
+});
+
+/**
+ * @param {string} spec
+ * @returns {boolean}
+ */
+function looksLikeRbacSpec(spec) {
+  if (!spec || typeof spec !== 'string') return false;
+  const trimmed = spec.trim();
+  if (/^(none|public)\b/i.test(trimmed) && !trimmed.includes(':')) return false;
+  if (/authenticated\s*\(/i.test(trimmed)) return false;
+  if (/client credentials/i.test(trimmed) && !/[a-z0-9_-]+:[a-z0-9_-]+/i.test(trimmed)) return false;
+  return /[a-z0-9_-]+:[a-z0-9_-]+/i.test(trimmed);
+}
+
+/**
+ * @param {string} spec
+ * @returns {string[]}
+ */
+function permissionListFromSpec(spec) {
+  const main = String(spec).split('(')[0].trim();
+  if (!main) return [];
+  if (/\bor\b/i.test(main)) return [main];
+  return main.split(/\s*\+\s*/).map((part) => part.trim()).filter(Boolean);
+}
+
+/**
+ * @param {string} template
+ * @returns {RegExp}
+ */
+function pathTemplateToRegex(template) {
+  const parts = String(template).split('/');
+  const escaped = parts.map((seg) => {
+    if (/^\{[^}]+\}$/.test(seg)) return '[^/]+';
+    return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }).join('/');
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * @param {string} block
+ * @returns {{ method: string, path: string, service: string, permissions: string[] }|null}
+ */
+function parsePermissionCommentBlock(block) {
+  const text = String(block).replace(/^\s*\*\s?/gm, '');
+  const methodPath = text.match(/\b(GET|POST|PUT|PATCH|DELETE)\s+(\/api\/[^\s*]+)/);
+  const perm = text.match(/@requiresPermission\s+\{([^}]+)\}\s+([^\n*]+)/);
+  if (!methodPath || !perm) return null;
+  const spec = String(perm[2] || '').trim();
+  if (!looksLikeRbacSpec(spec)) return null;
+  const permissions = permissionListFromSpec(spec);
+  if (permissions.length === 0) return null;
+  return {
+    method: methodPath[1].toUpperCase(),
+    path: methodPath[2].replace(/\/+$/, ''),
+    service: String(perm[1] || '').trim(),
+    permissions
+  };
+}
+
+/**
+ * @param {string} source
+ * @returns {Array<{ method: string, regex: RegExp, service: string, permissions: string[], pathLength: number }>}
+ */
+function parsePermissionEntriesFromSource(source) {
+  const entries = [];
+  const blocks = String(source).match(/\/\*\*[\s\S]*?\*\//g) || [];
+  for (const block of blocks) {
+    const parsed = parsePermissionCommentBlock(block);
+    if (!parsed) continue;
+    entries.push({
+      method: parsed.method,
+      regex: pathTemplateToRegex(parsed.path),
+      service: parsed.service,
+      permissions: parsed.permissions,
+      pathLength: parsed.path.length
+    });
+  }
+  return entries;
+}
+
+/**
+ * @returns {Array<{ method: string, regex: RegExp, service: string, permissions: string[], pathLength: number }>}
+ */
+function loadApiPermissionCatalog() {
+  if (cachedCatalog) return cachedCatalog;
+  const apiDir = path.join(__dirname, '..', 'api');
+  const entries = [];
+  let names = [];
+  try {
+    names = fsRealSync.readdirSync(apiDir);
+  } catch {
+    cachedCatalog = [];
+    return cachedCatalog;
+  }
+  for (const name of names) {
+    if (!name.endsWith('.api.js')) continue;
+    const source = fsRealSync.readFileSync(path.join(apiDir, name), 'utf8');
+    entries.push(...parsePermissionEntriesFromSource(source));
+  }
+  entries.sort((a, b) => b.pathLength - a.pathLength);
+  cachedCatalog = entries;
+  return cachedCatalog;
+}
+
+/**
+ * @param {string} [url]
+ * @returns {string}
+ */
+function apiPathFromUrl(url) {
+  const raw = String(url || '');
+  try {
+    const parsed = new URL(raw);
+    const idx = parsed.pathname.indexOf('/api/');
+    return idx >= 0 ? parsed.pathname.slice(idx).replace(/\/+$/, '') : parsed.pathname;
+  } catch {
+    const idx = raw.indexOf('/api/');
+    const pathOnly = idx >= 0 ? raw.slice(idx).split('?')[0] : raw.split('?')[0];
+    return pathOnly.replace(/\/+$/, '');
+  }
+}
+
+/**
+ * @param {string} [method]
+ * @param {string} [url]
+ * @returns {{ service: string, permissions: string[] }|null}
+ */
+function lookupRequiredPermission(method, url) {
+  const verb = String(method || '').toUpperCase();
+  const apiPath = apiPathFromUrl(url);
+  if (!verb || !apiPath.startsWith('/api/')) return null;
+  const catalog = loadApiPermissionCatalog();
+  for (const entry of catalog) {
+    if (entry.method === verb && entry.regex.test(apiPath)) {
+      return { service: entry.service, permissions: entry.permissions };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} [command]
+ * @returns {{ service: string, permissions: string[] }|null}
+ */
+function lookupCommandRequiredPermission(command) {
+  if (!command || typeof command !== 'string') return null;
+  return COMMAND_REQUIRED_PERMISSIONS[command] || null;
+}
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function extractPermissionTokensFromText(text) {
+  if (!text || typeof text !== 'string') return [];
+  const found = text.match(SCOPE_IN_TEXT_RE) || [];
+  const unique = [];
+  for (const token of found) {
+    const scheme = token.split(':')[0].toLowerCase();
+    if (SKIP_SCOPE_SCHEMES.has(scheme)) continue;
+    if (!unique.includes(token)) unique.push(token);
+  }
+  return unique;
+}
+
+/**
+ * @param {Object} data
+ * @returns {boolean}
+ */
+function hasBodyPermissionLists(data) {
+  if (!data || typeof data !== 'object') return false;
+  const lists = [
+    data.missingPermissions,
+    data.requiredPermissions,
+    data.permissions,
+    data.missing && data.missing.permissions,
+    data.required && data.required.permissions,
+    data.data && data.data.missing && data.data.missing.permissions,
+    data.data && data.data.required && data.data.required.permissions
+  ];
+  return lists.some((list) => Array.isArray(list) && list.length > 0);
+}
+
+/**
+ * @param {*} errorData
+ * @returns {Object}
+ */
+function asErrorObject(errorData) {
+  if (errorData && typeof errorData === 'object' && !Array.isArray(errorData)) {
+    return { ...errorData };
+  }
+  const text = errorData === undefined || errorData === null ? 'Permission denied' : String(errorData);
+  return { detail: text, message: text };
+}
+
+/**
+ * When a 403 body has no permission list, fill requiredPermissions from the request catalog.
+ *
+ * @param {*} errorData
+ * @param {{ status?: number, method?: string, url?: string }} [ctx]
+ * @returns {*}
+ */
+function enrichForbiddenErrorData(errorData, ctx = {}) {
+  if (ctx.status !== 403) return errorData;
+  const data = asErrorObject(errorData);
+  if (ctx.method && !data.method) data.method = ctx.method;
+  if (ctx.url && !data.instance && !data.url) data.url = ctx.url;
+  if (hasBodyPermissionLists(data)) {
+    return data;
+  }
+  const fromText = extractPermissionTokensFromText(
+    [data.detail, data.message, data.error, data.title, data.errorDescription].filter(Boolean).join(' ')
+  );
+  if (fromText.length > 0) {
+    data.requiredPermissions = fromText;
+    return data;
+  }
+  const hit = lookupRequiredPermission(ctx.method, ctx.url);
+  if (!hit) return data;
+  data.cliPermissionService = hit.service;
+  data.requiredPermissions = hit.permissions;
+  return data;
+}
+
+module.exports = {
+  lookupRequiredPermission,
+  lookupCommandRequiredPermission,
+  enrichForbiddenErrorData,
+  extractPermissionTokensFromText,
+  parsePermissionEntriesFromSource,
+  parsePermissionCommentBlock,
+  apiPathFromUrl,
+  COMMAND_REQUIRED_PERMISSIONS
+};

package/lib/utils/api.js

@@ -98,7 +98,12 @@ function parseErrorText(errorText, status, statusText) {
 async function handleErrorResponse(response, url, options, duration) {
   const errorText = await response.text();
   const errorData = parseErrorText(errorText, response.status, response.statusText);
-  const parsedError = parseErrorResponse(errorData, response.status, false);
+  const { enrichForbiddenErrorData } = require('./api-required-permissions');
+  const parsedError = parseErrorResponse(enrichForbiddenErrorData(errorData, {
+    status: response.status,
+    method: options && options.method,
+    url
+  }), response.status, false);
 
   await logApiPerformance({
     url,
@@ -406,21 +411,14 @@ function setAuthHeader(headers, token, authType) {
  * @param {string} [tokenOrAuthConfig.controller] - Controller URL for token refresh (if object)
  * @returns {Promise<Object>} Response object
  */
-/**
- * Retry once after device-token refresh on 401 (Bearer only; never for client-token/preserveBearer).
- * @param {Object} response
- * @param {string} url
- * @param {Object} options
- * @param {Object} headers
- * @param {string|null} authControllerUrl
- * @returns {Promise<Object>}
- */
+/** Retry once after device-token refresh on 401 (Bearer only). */
 async function retryApiCallAfterDeviceTokenRefresh(
   response,
   url,
   options,
   headers,
-  authControllerUrl
+  authControllerUrl,
+  authConfig
 ) {
   try {
     const { forceRefreshDeviceToken } = require('./token-manager');
@@ -429,6 +427,11 @@ async function retryApiCallAfterDeviceTokenRefresh(
     );
     if (refreshedToken?.token) {
       headers.Authorization = `Bearer ${refreshedToken.token}`;
+      // Keep long-running commands current instead of reusing the expired bearer.
+      if (authConfig && typeof authConfig === 'object') {
+        authConfig.token = refreshedToken.token;
+        authConfig.controller = refreshedToken.controller || authControllerUrl;
+      }
       return await makeApiCall(url, { ...options, headers });
     }
     const authError =
@@ -471,7 +474,8 @@ async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
       url,
       options,
       headers,
-      authControllerUrl
+      authControllerUrl,
+      isStringToken ? null : tokenOrAuthConfig
     );
   }
 
@@ -492,4 +496,3 @@ module.exports = {
   displayDeviceCodeInfo,
   refreshDeviceToken
 };
-

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

@@ -0,0 +1,41 @@
+/**
+ * Truncation-safe JSON stdout write + exit for CLI commands.
+ *
+ * @fileoverview Shared helper for `--json` command output followed by a
+ *   non-zero process exit.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('./logger');
+const { writeStreamAndWait } = require('./write-stream-and-wait');
+
+/**
+ * Write a JSON envelope to stdout and exit with the given code, without
+ * truncating the output.
+ *
+ * Writes to a piped (non-TTY) stdout are asynchronous on Linux; calling
+ * `process.exit()` immediately after `logger.log()`/`console.log()` can
+ * kill the process before the OS finishes flushing a large write, silently
+ * truncating the JSON. Waiting for the `stdout.write` callback before
+ * exiting avoids that. Applies `logger.sanitizeValue` first, when available,
+ * so token/secret masking still happens (bypassing `logger.log()` skips it
+ * otherwise) — falls back to an identity function for test doubles that
+ * mock `logger` without it.
+ *
+ * @param {unknown} payload - Value to serialize as the JSON envelope.
+ * @param {number} exitCode - Exit code; 0 resolves without exiting.
+ * @returns {Promise<void>}
+ */
+async function writeJsonEnvelopeAndExit(payload, exitCode) {
+  const sanitize = typeof logger.sanitizeValue === 'function' ? logger.sanitizeValue : v => v;
+  const json = `${JSON.stringify(sanitize(payload), null, 2)}\n`;
+  await writeStreamAndWait(process.stdout, json);
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}
+
+module.exports = { writeJsonEnvelopeAndExit };

package/lib/utils/cli-utils.js

@@ -83,9 +83,11 @@ function isPortConflictError(errorMsg) {
  * @returns {boolean} True if permission denied error
  */
 function isPermissionDeniedError(errorMsg) {
-  return (errorMsg.includes('permission denied') || errorMsg.includes('EACCES') || errorMsg.includes('Permission denied')) &&
-    !errorMsg.includes('permissions/') &&
-    !errorMsg.includes('Field "permissions');
+  const text = String(errorMsg || '');
+  const lower = text.toLowerCase();
+  return (lower.includes('permission denied') || lower.includes('eacces')) &&
+    !text.includes('permissions/') &&
+    !text.includes('Field "permissions');
 }
 
 /**
@@ -287,7 +289,7 @@ function formatApiPermissionError(errorMsg) {
   if (isLocalFilesystemPermissionDeniedError(errorMsg)) return null;
   return [
     `   ${errorMsg}`,
-    '   Ensure your token has the required permission (e.g. external-system:delete for delete).'
+    '   Assign the required permission on the Controller or Dataplane for this environment (roles and groups).'
   ];
 }
 
@@ -418,11 +420,27 @@ function isAuthenticationError(error) {
  * @param {Error} error - The error that occurred
  * @param {string} command - Command that failed
  */
+function appendCommandPermissionHint(errorMessages, command) {
+  const blob = Array.isArray(errorMessages) ? errorMessages.join('\n') : '';
+  if (!isPermissionDeniedError(blob)) return errorMessages;
+  if (/Required permissions:|Missing permissions:|Required permission \(/.test(blob)) {
+    return errorMessages;
+  }
+  const { lookupCommandRequiredPermission } = require('./api-required-permissions');
+  const hit = lookupCommandRequiredPermission(command);
+  if (!hit) return errorMessages;
+  return [
+    ...errorMessages,
+    `   Required permission (${hit.service}): ${hit.permissions.join(', ')}`,
+    `   Assign it on the ${hit.service} for this environment (roles and groups).`
+  ];
+}
+
 function handleCommandError(error, command) {
   if (error && error.compactGateAbortLogged === true) {
     return;
   }
-  const errorMessages = formatError(error);
+  const errorMessages = appendCommandPermissionHint(formatError(error), command);
   const skipDoctor = isMissingSecretsErrorMessage(error && error.message);
   logError(command, errorMessages, { skipDoctor });
   if (error.wizardResumeMessage) {

package/lib/utils/controller-url.js

@@ -14,6 +14,10 @@ const devConfig = require('./dev-config');
 const config = require('../core/config');
 const { getDeviceToken, isTokenExpired } = require('./token-manager');
 
+/** Default Front Door / Traefik mount for Miso Controller on public hosts. */
+const DEFAULT_CONTROLLER_VDIR = '/miso';
+const CONTROLLER_HEALTH_TIMEOUT_MS = 2500;
+
 /**
  * Calculate default controller URL based on developer ID
  * Uses getDevPorts to get the app port which is adjusted by developer ID
@@ -132,14 +136,58 @@ async function isPlatformAuthValidForController(controllerUrl) {
 }
 
 /**
- * Best-effort GET /health on the controller (no auth). Used to avoid token refresh HTTP
- * during setup before Miso Controller is running.
+ * True for local controller ports (no Front Door /miso vdir).
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function isLoopbackControllerHost(hostname) {
+  const host = String(hostname || '').toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+}
+
+/**
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+function isMisoVdirPath(pathname) {
+  return pathname === DEFAULT_CONTROLLER_VDIR
+    || pathname.startsWith(`${DEFAULT_CONTROLLER_VDIR}/`);
+}
+
+/**
+ * Strip extra path segments. Public hosts always use origin + /miso.
+ * Loopback keeps origin unless the path is already /miso.
  *
+ * @param {string} url
+ * @returns {string}
+ */
+function canonicalizeControllerLoginUrl(url) {
+  const base = normalizeUrl(url);
+  if (!base) {
+    return url;
+  }
+  let parsed;
+  try {
+    parsed = new URL(base);
+  } catch {
+    return base;
+  }
+  const origin = `${parsed.protocol}//${parsed.host}`;
+  const pathname = (parsed.pathname || '/').replace(/\/+$/, '') || '/';
+  if (isLoopbackControllerHost(parsed.hostname)) {
+    return isMisoVdirPath(pathname) ? `${origin}${DEFAULT_CONTROLLER_VDIR}` : origin;
+  }
+  return `${origin}${DEFAULT_CONTROLLER_VDIR}`;
+}
+
+/**
+ * Best-effort GET /health on the controller (no auth).
  * @async
  * @param {string} controllerUrl
+ * @param {number} timeoutMs
  * @returns {Promise<boolean>}
  */
-async function isControllerHealthReachable(controllerUrl) {
+async function probeControllerHealth(controllerUrl, timeoutMs) {
   const base = normalizeUrl(controllerUrl);
   if (!base) {
     return false;
@@ -147,7 +195,7 @@ async function isControllerHealthReachable(controllerUrl) {
   try {
     const { fetchWithOptionalDevPlatformTls } = require('./dev-platform-tls');
     const res = await fetchWithOptionalDevPlatformTls(`${base}/health`, {
-      signal: AbortSignal.timeout(2500)
+      signal: AbortSignal.timeout(timeoutMs)
     });
     return res.ok;
   } catch {
@@ -155,6 +203,29 @@ async function isControllerHealthReachable(controllerUrl) {
   }
 }
 
+/**
+ * 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) {
+  return probeControllerHealth(controllerUrl, CONTROLLER_HEALTH_TIMEOUT_MS);
+}
+
+/**
+ * Resolve a controller base URL for login: public hosts always origin + /miso.
+ *
+ * @async
+ * @param {string} controllerUrl
+ * @returns {Promise<string>} Canonical controller URL
+ */
+async function discoverControllerBaseUrl(controllerUrl) {
+  return canonicalizeControllerLoginUrl(controllerUrl);
+}
+
 /**
  * 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
@@ -237,11 +308,14 @@ async function resolveControllerUrl() {
 }
 
 module.exports = {
+  DEFAULT_CONTROLLER_VDIR,
   getDefaultControllerUrl,
   hasStoredDeviceTokenForController,
   isDeviceTokenUsableForController,
   isPlatformAuthValidForController,
   isControllerHealthReachable,
+  canonicalizeControllerLoginUrl,
+  discoverControllerBaseUrl,
   getControllerUrlFromLoggedInUser,
   getControllerFromConfig,
   resolveControllerUrl

package/lib/utils/deployment-errors.js

@@ -193,6 +193,17 @@ function createFormattedError(parsedError, safeError, originalError) {
   return formattedError;
 }
 
+function createPreservedFormattedError(error, safeError) {
+  if (!error || typeof error.formatted !== 'string' || !error.formatted.trim()) {
+    return null;
+  }
+  return createFormattedError({
+    message: error.message || error.formatted,
+    formatted: error.formatted,
+    data: error.data
+  }, safeError, error);
+}
+
 /**
  * Unified error handler for deployment errors
  * Handles audit logging, error formatting, and user-friendly messages
@@ -227,6 +238,10 @@ async function handleDeploymentErrors(error, appName, url, alreadyLogged = false
   }
 
   const safeError = handleDeploymentError(error);
+  const preserved = createPreservedFormattedError(error, safeError);
+  if (preserved) {
+    throw preserved;
+  }
   const errorResponse = extractErrorResponse(safeError, error);
   const parsedError = parseErrorResponseSafely(errorResponse, safeError);
 

package/lib/utils/deployment-validation-helpers.js

@@ -49,7 +49,10 @@ function processValidationFailure(responseData) {
 function processValidationError(response) {
   const error = new Error(`Validation request failed: ${response.formattedError || response.error || 'Unknown error'}`);
   error.status = response.status || 400;
-  error.data = response.data;
+  error.data = response.errorData || response.data;
+  if (response.formattedError) {
+    error.formatted = response.formattedError;
+  }
   throw error;
 }
 

package/lib/utils/device-code.js

@@ -128,25 +128,45 @@ function buildVerificationUrlWithUserCode(verificationUri, userCode) {
 }
 
 /**
- * Displays device code information to the user
- * Formats user code and verification URL for easy reading. Uses a URL with user_code in the query
- * so the device page can pre-fill the code and the user does not need to type it.
+ * Full visit URL for device login (complete URI when the controller sends one).
+ *
+ * @param {Object} deviceCodeResponse
+ * @param {string} [deviceCodeResponse.verification_uri_complete]
+ * @param {string} [deviceCodeResponse.verification_uri]
+ * @param {string} [deviceCodeResponse.user_code]
+ * @returns {string}
+ */
+function resolveDeviceVisitUrl(deviceCodeResponse) {
+  const complete = deviceCodeResponse && deviceCodeResponse.verification_uri_complete;
+  if (complete) {
+    return complete;
+  }
+  return buildVerificationUrlWithUserCode(
+    deviceCodeResponse && deviceCodeResponse.verification_uri,
+    deviceCodeResponse && deviceCodeResponse.user_code
+  );
+}
+
+/**
+ * Displays device code information to the user.
+ * Prints a visit URL with user_code so the device page can pre-fill the code.
  *
  * @function displayDeviceCodeInfo
  * @param {string} userCode - User code to display
  * @param {string} verificationUri - Verification URL (base, without user_code)
  * @param {Object} logger - Logger instance with log method
  * @param {Object} chalk - Chalk instance for colored output
+ * @param {string} [verificationUriComplete] - Full verification URL when provided by the controller
  */
-function displayDeviceCodeInfo(userCode, verificationUri, logger, chalk) {
-  const visitUrl = buildVerificationUrlWithUserCode(verificationUri, userCode);
+function displayDeviceCodeInfo(userCode, verificationUri, logger, chalk, verificationUriComplete) {
+  const visitUrl = verificationUriComplete
+    || buildVerificationUrlWithUserCode(verificationUri, userCode);
   logger.log(chalk.cyan('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
   logger.log(chalk.cyan('  Device Code Flow Authentication'));
   logger.log(chalk.cyan('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
-  logger.log(chalk.yellow('To complete authentication:'));
-  logger.log(chalk.gray('  1. Visit (code is in the URL): ') + chalk.blue.underline(visitUrl));
-  logger.log(chalk.gray('  2. Approve the request\n'));
-  logger.log(chalk.gray('Waiting for approval...'));
+  logger.log(chalk.yellow('Open this URL to authenticate:'));
+  logger.log(chalk.blue.underline(visitUrl));
+  logger.log(chalk.gray('\nApprove the request in the browser. Waiting for approval...'));
 }
 
 /** Timeout for token refresh request (ms). Longer than default to allow for slow controller/Keycloak. */
@@ -197,5 +217,6 @@ module.exports = {
   displayDeviceCodeInfo,
   refreshDeviceToken,
   parseTokenResponse,
-  buildVerificationUrlWithUserCode
+  buildVerificationUrlWithUserCode,
+  resolveDeviceVisitUrl
 };