@aifabrix/builder 2.45.5 → 2.46.0

package/lib/utils/api.js

@@ -10,7 +10,8 @@
  * @version 2.0.0
  */
 
-const { parseErrorResponse } = require('./api-error-handler');
+const { parseErrorResponse, formatNetworkError } = require('./api-error-handler');
+const { inferServiceLabelFromUrl } = require('./service-url-label');
 const auditLogger = require('../core/audit-logger');
 
 /** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
@@ -172,7 +173,7 @@ async function handleSuccessResponse(response, url, options, duration) {
  * @throws {Error} If URL is empty, null, undefined, whitespace-only, or malformed
  */
 function validateUrl(url, urlType = 'URL') {
-  if (!url || typeof url !== 'string') {
+  if (url === null || url === undefined || typeof url !== 'string') {
     throw new Error(`${urlType} is required and must be a string (received: ${JSON.stringify(url)})`);
   }
   const trimmedUrl = url.trim();
@@ -248,20 +249,18 @@ async function handleNetworkError(error, url, options, duration) {
   const flat = flattenNetworkErrorDetail(error);
   const errorMessage = withUrlContextForNetworkError(flat || error.message, url);
 
-  const parsedError = parseErrorResponse(errorMessage, 0, true);
-
-  // Extract controller URL from full URL for error data
-  let controllerUrl = null;
+  let serviceBaseUrl = null;
   const endpointUrl = url;
   if (url && typeof url === 'string' && url.trim()) {
     try {
       const urlObj = new URL(url);
-      controllerUrl = `${urlObj.protocol}//${urlObj.host}`;
+      serviceBaseUrl = `${urlObj.protocol}//${urlObj.host}`;
     } catch {
-      // If URL parsing fails, use the full URL as endpoint
-      controllerUrl = null;
+      serviceBaseUrl = null;
     }
   }
+  const serviceLabel = inferServiceLabelFromUrl(endpointUrl);
+  const parsedError = parseErrorResponse(errorMessage, 0, true);
 
   await logApiPerformance({
     url,
@@ -276,24 +275,61 @@ async function handleNetworkError(error, url, options, duration) {
     }
   });
 
-  // Include both controller URL and full endpoint URL in error data
   const errorData = {
-    ...parsedError.data,
-    controllerUrl: controllerUrl,
-    endpointUrl: endpointUrl
+    controllerUrl: serviceBaseUrl,
+    endpointUrl: endpointUrl,
+    serviceLabel
   };
+  const formattedError = formatNetworkError(errorMessage, errorData);
 
   return {
     success: false,
-    error: parsedError.message,
+    error: errorMessage,
     errorData: errorData,
-    errorType: parsedError.type,
-    formattedError: parsedError.formatted,
+    errorType: 'network',
+    formattedError,
     network: true,
     originalError: error
   };
 }
 
+/**
+ * @param {Object} options - Fetch options passed to makeApiCall
+ * @returns {{ fetchOptions: Object, singleRequestTimeoutMs: number }}
+ */
+function prepareFetchOptionsForRequest(options) {
+  const fetchOptions = { ...options };
+  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
+  if (!fetchOptions.signal) {
+    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
+  }
+  delete fetchOptions.timeoutMs;
+  delete fetchOptions.requestTimeoutMs;
+  return { fetchOptions, singleRequestTimeoutMs };
+}
+
+/**
+ * @param {Error} err
+ * @param {string} url
+ * @param {number} singleRequestTimeoutMs
+ * @returns {Error}
+ */
+function normalizeFetchNetworkError(err, url, singleRequestTimeoutMs) {
+  if (err?.name !== 'AbortError') {
+    return err;
+  }
+  const serviceLabel = inferServiceLabelFromUrl(url);
+  const serviceName =
+    serviceLabel === 'dataplane'
+      ? 'dataplane'
+      : serviceLabel === 'controller'
+        ? 'controller'
+        : 'service';
+  return new Error(
+    `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The ${serviceName} may be unreachable. Check the URL and network.`
+  );
+}
+
 /**
  * Make an API call with proper error handling
  * Uses a 30s timeout by default. Pass ``options.timeoutMs`` or ``options.requestTimeoutMs`` for
@@ -304,22 +340,14 @@ async function handleNetworkError(error, url, options, duration) {
  * @returns {Promise<Object>} Response object with success flag
  */
 async function makeApiCall(url, options = {}) {
-  // Validate URL before attempting request
   try {
     validateUrl(url, 'API endpoint URL');
   } catch (error) {
-    const duration = 0;
-    return await handleNetworkError(error, url || '', options, duration);
+    return await handleNetworkError(error, url || '', options, 0);
   }
 
   const startTime = Date.now();
-  const fetchOptions = { ...options };
-  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
-  if (!fetchOptions.signal) {
-    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
-  }
-  delete fetchOptions.timeoutMs;
-  delete fetchOptions.requestTimeoutMs;
+  const { fetchOptions, singleRequestTimeoutMs } = prepareFetchOptionsForRequest(options);
 
   try {
     const response = await fetch(url, fetchOptions);
@@ -332,11 +360,7 @@ async function makeApiCall(url, options = {}) {
     return await handleSuccessResponse(response, url, options, duration);
   } catch (err) {
     const duration = Date.now() - startTime;
-    const error = err?.name === 'AbortError'
-      ? new Error(
-        `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The controller may be unreachable. Check the URL and network.`
-      )
-      : err;
+    const error = normalizeFetchNetworkError(err, url, singleRequestTimeoutMs);
     return await handleNetworkError(error, url, options, duration);
   }
 }

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-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-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