@aifabrix/builder 2.44.5 → 2.44.6

package/lib/utils/secrets-helpers.js

@@ -19,6 +19,7 @@ const { updateContainerPortInEnvFile } = require('./env-ports');
 const { buildEnvVarMap } = require('./env-map');
 const { getLocalPortFromPath } = require('./port-resolver');
 const { readYamlAtPath, applyCanonicalSecretsOverride } = require('./secrets-canonical');
+const { collectUniqueKvPathStrings } = require('./secrets-kv-refs');
 
 /**
  * Interpolate ${VAR} occurrences with values from envVars map
@@ -51,9 +52,13 @@ const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
 /**
  * Last-resort when infra.parameter.yaml cannot be read (e.g. Jest suites that mock `fs`;
  * catalog uses `node:fs`, which is often the same mocked instance). Must stay in sync with
- * `generator.type: emptyAllowed` keys in lib/schema/infra.parameter.yaml.
+ * `generator.type: emptyAllowed` keys in lib/schema/infra.parameter.yaml; plus optional Azure/OpenAI kv names.
  */
-const EMPTY_ALLOWED_KV_FALLBACK = new Set(['redis-passwordKeyVault']);
+const EMPTY_ALLOWED_KV_FALLBACK = new Set([
+  'redis-passwordKeyVault',
+  'azure-openaiapi-urlKeyVault',
+  'secrets-azureOpenaiApiKeyVault'
+]);
 
 /**
  * Infra catalog keys with generator `emptyAllowed` may be absent from the secrets file;
@@ -191,7 +196,12 @@ function formatMissingSecretsFileInfo(secretsFilePaths) {
     if (secretsFilePaths.buildPath) {
       paths.push(secretsFilePaths.buildPath);
     }
-    return `\n\nSecrets file location: ${paths.join(' and ')}`;
+    let msg = `\n\nSecrets file location: ${paths.join(' and ')}`;
+    if (secretsFilePaths.sharedSecretsApiUrl && typeof secretsFilePaths.sharedSecretsApiUrl === 'string') {
+      msg +=
+        `\n(Shared secrets API: ${secretsFilePaths.sharedSecretsApiUrl.trim()}. Keys from that API are merged when resolving secrets; if a key is still missing, add it via "aifabrix secret set" / shared store or check "aifabrix secret list --shared".)`;
+    }
+    return msg;
   }
   return '';
 }
@@ -459,13 +469,7 @@ async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   return updated;
 }
 
-/**
- * Validate secrets against the env template (skips commented and empty lines)
- * @function validateSecrets
- * @param {string} envTemplate - Environment template content
- * @param {Object} secrets - Available secrets
- * @returns {Object} Validation result
- */
+/** Validate secrets vs env template (commented/empty lines skipped). */
 function validateSecrets(envTemplate, secrets) {
   const missing = collectMissingSecrets(envTemplate, secrets);
   return { valid: missing.length === 0, missing };
@@ -475,6 +479,9 @@ module.exports = {
   loadEnvConfig,
   interpolateEnvVars,
   collectMissingSecrets,
+  collectUniqueKvPathStrings,
+  resolveKvRefValue,
+  isKvKeyAllowedEmptyWhenAbsent,
   resolveBashKvFromProcessEnv,
   mergeSecretsWithPrefixedCopies,
   formatMissingSecretsFileInfo,

package/lib/utils/secrets-kv-refs.js

@@ -0,0 +1,42 @@
+/**
+ * Scan env-style content for unique kv:// path segments (comments skipped).
+ * @fileoverview Keeps secrets-helpers under max-lines
+ */
+
+'use strict';
+
+const KV_REF_PATTERN = /kv:\/\/([a-zA-Z0-9_\-/]+)/g;
+
+function isCommentOrEmptyLine(line) {
+  const t = line.trim();
+  return t === '' || t.startsWith('#');
+}
+
+/**
+ * @param {string} content
+ * @returns {string[]}
+ */
+function collectUniqueKvPathStrings(content) {
+  const seen = new Set();
+  const out = [];
+  if (!content || typeof content !== 'string') {
+    return out;
+  }
+  for (const line of content.split('\n')) {
+    if (isCommentOrEmptyLine(line)) continue;
+    let match;
+    KV_REF_PATTERN.lastIndex = 0;
+    while ((match = KV_REF_PATTERN.exec(line)) !== null) {
+      const pathStr = match[1];
+      if (!seen.has(pathStr)) {
+        seen.add(pathStr);
+        out.push(pathStr);
+      }
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  collectUniqueKvPathStrings
+};

package/lib/utils/secrets-kv-scope.js

@@ -8,6 +8,23 @@
 
 'use strict';
 
+/**
+ * Treat undefined/null and whitespace-only strings as no value so prefixed slots
+ * cannot shadow unprefixed secrets with empty placeholders (plan 117 scoped KV).
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+function isKvSlotEmpty(v) {
+  if (v === undefined || v === null) {
+    return true;
+  }
+  if (typeof v === 'string' && v.trim() === '') {
+    return true;
+  }
+  return false;
+}
+
 /**
  * @param {Function} getValueByPath - From secrets-helpers
  * @returns {{ getValueByPathWithEnvScope: Function, mergeSecretsWithPrefixedCopies: Function }}
@@ -27,7 +44,7 @@ function createScopedKvHelpers(getValueByPath) {
     const prefix = `${String(envKey).toLowerCase()}-`;
     const prefixedPath = prefix + pathStr;
     const fromPrefixed = getValueByPath(secrets, prefixedPath);
-    if (fromPrefixed !== undefined && fromPrefixed !== null) {
+    if (!isKvSlotEmpty(fromPrefixed)) {
       return fromPrefixed;
     }
     return getValueByPath(secrets, pathStr);
@@ -47,7 +64,7 @@ function createScopedKvHelpers(getValueByPath) {
     for (const [k, v] of Object.entries(secrets)) {
       if (typeof k !== 'string' || !k || k.startsWith(prefix)) continue;
       const pk = prefix + k;
-      if (merged[pk] === undefined && v !== undefined && v !== null) {
+      if (isKvSlotEmpty(merged[pk]) && !isKvSlotEmpty(v)) {
         merged[pk] = v;
       }
     }

package/lib/utils/secrets-materialize-local.js

@@ -0,0 +1,134 @@
+/**
+ * Persist resolved kv:// values into the primary user secrets file so regenerate (.env) stays stable.
+ *
+ * @fileoverview After env.template resolves, copy merged secret values into ~/.aifabrix/secrets.local.yaml
+ * when keys are missing or empty locally **and** not already provided by the configured shared store
+ * (`aifabrix-secrets` remote API or shared YAML), so shared-only keys are not duplicated into user secrets.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('./logger');
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
+const localSecretsModule = require('./local-secrets');
+const secretsUtils = require('./secrets-utils');
+const { loadConfiguredSharedSecretsStore } = require('./remote-secrets-loader');
+const { decryptSecretsObject } = require('../core/secrets-load');
+const { collectUniqueKvPathStrings } = require('./secrets-kv-refs');
+const {
+  resolveKvRefValue,
+  mergeSecretsWithPrefixedCopies,
+  isKvKeyAllowedEmptyWhenAbsent
+} = require('./secrets-helpers');
+
+/**
+ * After successful kv resolution, write resolved values to the user secrets file when local slot is empty.
+ * Does not overwrite non-empty local values (user wins).
+ *
+ * @async
+ * @param {string} templateContent - Original env.template text (still contains kv:// refs)
+ * @param {Object} mergedSecrets - Decrypted secrets map passed to resolveKvReferences (same as loadSecrets output)
+ * @param {{ effective?: boolean, envKey?: string }|null} scopedKv - Scoped kv context from generateEnvContent
+ * @param {Object} [options]
+ * @param {boolean} [options.skipMaterializeKvToLocal] - Skip persistence (tests / programmatic)
+ * @returns {Promise<string[]>} Keys materialized (written) to local file
+ */
+function buildScopedMaps(mergedSecrets, scopedKv) {
+  const effective = Boolean(scopedKv && scopedKv.effective && scopedKv.envKey);
+  const secretsMap = effective ? mergeSecretsWithPrefixedCopies(mergedSecrets, scopedKv.envKey) : mergedSecrets;
+  const rawLocal = secretsUtils.loadPrimaryUserSecrets();
+  const localMap = effective ? mergeSecretsWithPrefixedCopies(rawLocal, scopedKv.envKey) : rawLocal;
+  return { effective, secretsMap, localMap };
+}
+
+function shouldSkipPersist(pathStr, resolvedVal, localVal) {
+  if (resolvedVal === undefined || resolvedVal === null) return true;
+  if (
+    typeof resolvedVal === 'string' &&
+    resolvedVal.trim() === '' &&
+    isKvKeyAllowedEmptyWhenAbsent(pathStr)
+  ) {
+    return true;
+  }
+  if (localVal !== undefined && localVal !== null && String(localVal).trim() !== '') {
+    return true;
+  }
+  return false;
+}
+
+function isNonEmptyResolvedKv(val) {
+  if (val === undefined || val === null) return false;
+  if (typeof val === 'string' && val.trim() === '') return false;
+  return true;
+}
+
+async function resolveSharedScopedMapForMaterialize(scopedKv, effective) {
+  try {
+    const rawShared = await loadConfiguredSharedSecretsStore();
+    const decryptedShared = rawShared ? await decryptSecretsObject(rawShared) : null;
+    if (!decryptedShared) return null;
+    return effective && scopedKv && scopedKv.envKey
+      ? mergeSecretsWithPrefixedCopies(decryptedShared, scopedKv.envKey)
+      : decryptedShared;
+  } catch {
+    return null;
+  }
+}
+
+function plaintextKvForLocalPersist(pathStr, secretsMap, localMap, sharedScoped, scopedKv, effective) {
+  const resolvedVal = resolveKvRefValue(secretsMap, pathStr, scopedKv?.envKey, effective);
+  const localVal = resolveKvRefValue(localMap, pathStr, scopedKv?.envKey, effective);
+  if (shouldSkipPersist(pathStr, resolvedVal, localVal)) return null;
+  const sharedVal =
+    sharedScoped && typeof sharedScoped === 'object'
+      ? resolveKvRefValue(sharedScoped, pathStr, scopedKv?.envKey, effective)
+      : undefined;
+  if (isNonEmptyResolvedKv(sharedVal)) return null;
+  return typeof resolvedVal === 'string' ? resolvedVal : String(resolvedVal);
+}
+
+async function materializeResolvedKvSecretsToUserLocal(templateContent, mergedSecrets, scopedKv, options = {}) {
+  if (
+    !templateContent ||
+    typeof templateContent !== 'string' ||
+    options.skipMaterializeKvToLocal === true
+  ) {
+    return [];
+  }
+
+  try {
+    const { effective, secretsMap, localMap } = buildScopedMaps(mergedSecrets, scopedKv);
+    const sharedScoped = await resolveSharedScopedMapForMaterialize(scopedKv, effective);
+
+    const paths = collectUniqueKvPathStrings(templateContent);
+    const materialized = [];
+
+    for (const pathStr of paths) {
+      const plain = plaintextKvForLocalPersist(pathStr, secretsMap, localMap, sharedScoped, scopedKv, effective);
+      if (plain === null) continue;
+      await localSecretsModule.saveLocalSecret(pathStr, plain);
+      materialized.push(pathStr);
+    }
+
+    if (materialized.length > 0) {
+      logger.log(
+        formatSuccessLine(
+          `Saved ${materialized.length} resolved kv key(s) to local secrets for stable reinstalls: ${materialized.join(', ')}`
+        )
+      );
+    }
+
+    return materialized;
+  } catch (err) {
+    if (typeof logger.warn === 'function') {
+      logger.warn(`Could not materialize resolved kv secrets to local file: ${err.message}`);
+    }
+    return [];
+  }
+}
+
+module.exports = {
+  materializeResolvedKvSecretsToUserLocal
+};

package/lib/utils/secrets-path.js

@@ -13,6 +13,15 @@ const path = require('path');
 const config = require('../core/config');
 const paths = require('./paths');
 
+/**
+ * @param {string} s
+ * @returns {boolean}
+ */
+function isHttpOrHttpsUrl(s) {
+  const t = String(s || '').trim();
+  return t.startsWith('http://') || t.startsWith('https://');
+}
+
 /**
  * Resolves secrets file path when an explicit path is provided.
  * If not provided, returns default fallback under <home>/secrets.yaml.
@@ -42,7 +51,8 @@ function resolveSecretsPath(secretsPath) {
  * @param {string} [_appName] - Application name (optional, for backward compatibility, unused)
  * @returns {Promise<Object>} Object with userPath and buildPath (if configured)
  * @returns {string} returns.userPath - User's secrets file path (~/.aifabrix/secrets.local.yaml)
- * @returns {string|null} returns.buildPath - App's secrets file path (if configured in config.yaml)
+ * @returns {string|null} returns.buildPath - On-disk shared secrets file (if configured; never an http(s) URL)
+ * @returns {string|null} [returns.sharedSecretsApiUrl] - When aifabrix-secrets is an API URL (for error messages; loadSecrets merges this API into the kv:// resolution map)
  */
 async function getActualSecretsPath(secretsPath, _appName) {
   // If explicit path provided, use it (backward compatibility)
@@ -50,30 +60,34 @@ async function getActualSecretsPath(secretsPath, _appName) {
     const resolvedPath = resolveSecretsPath(secretsPath);
     return {
       userPath: resolvedPath,
-      buildPath: null
+      buildPath: null,
+      sharedSecretsApiUrl: null
     };
   }
 
-  // Cascading lookup: user's file first (primary home: AIFABRIX_HOME or ~/.aifabrix)
-  const userSecretsPath = path.join(paths.getConfigDirForPaths(), 'secrets.local.yaml');
+  // Cascading lookup: user's file first (same path as `secret set`: getPrimaryUserSecretsLocalPath)
+  const userSecretsPath = paths.getPrimaryUserSecretsLocalPath();
 
-  // Check config.yaml for canonical secrets path
   let buildSecretsPath = null;
+  let sharedSecretsApiUrl = null;
   try {
     const canonicalSecretsPath = await config.getAifabrixSecretsPath();
     if (canonicalSecretsPath) {
-      buildSecretsPath = path.isAbsolute(canonicalSecretsPath)
-        ? canonicalSecretsPath
-        : path.resolve(process.cwd(), canonicalSecretsPath);
+      const raw = String(canonicalSecretsPath).trim();
+      if (isHttpOrHttpsUrl(raw)) {
+        sharedSecretsApiUrl = raw.replace(/\/+$/, '');
+      } else {
+        buildSecretsPath = path.isAbsolute(raw) ? raw : path.resolve(process.cwd(), raw);
+      }
     }
   } catch (error) {
     // Ignore errors, continue
   }
 
-  // Return both paths (even if files don't exist) for error messages
   return {
     userPath: userSecretsPath,
-    buildPath: buildSecretsPath
+    buildPath: buildSecretsPath,
+    sharedSecretsApiUrl
   };
 }
 

package/lib/utils/secrets-utils.js

@@ -58,7 +58,7 @@ async function loadSecretsFromFile(filePath) {
 }
 
 /**
- * Loads user secrets from getPrimaryUserSecretsLocalPath() (same dir as config.yaml resolution).
+ * Loads user secrets from getPrimaryUserSecretsLocalPath() (under {@link module:lib/utils/paths.getAifabrixHome}).
  * Used as the master source when merging with project/public secrets: user values win,
  * missing keys are filled from the public (aifabrix-secrets) file.
  *
@@ -128,7 +128,7 @@ function loadDefaultSecrets() {
 
 /**
  * Creates the primary user secrets file if missing (empty map) for first-run installs.
- * Uses the same directory as {@link loadPrimaryUserSecrets} (config dir / ~/.aifabrix).
+ * Uses the same directory as {@link loadPrimaryUserSecrets} (resolved AI Fabrix home).
  *
  * @function ensurePrimaryUserSecretsFileExists
  */

package/lib/utils/system-builder-root.js

@@ -0,0 +1,34 @@
+/**
+ * Picks the parent directory for platform `builder/<app>` materialization when the project has no
+ * `builder/<app>`. Compares the effective config directory (`getAifabrixSystemDir`) to the resolved
+ * AI Fabrix home (`getAifabrixHome`, from `AIFABRIX_HOME` or `aifabrix-home` in config.yaml).
+ *
+ * @fileoverview System builder root parent (config dir vs home override)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * When the effective config directory lies under the resolved AI Fabrix home, keep state (including
+ * `builder/`) beside `config.yaml` (e.g. `$HOME/.aifabrix/builder` when `AIFABRIX_HOME=$HOME`).
+ * When `aifabrix-home` relocates home outside the config tree, materialize under that home instead.
+ *
+ * @param {string} systemDir - Absolute config/state directory (same as `getAifabrixSystemDir()`).
+ * @param {string} homeDir - Absolute AI Fabrix home (`getAifabrixHome()`).
+ * @returns {string} Absolute directory whose `builder/` subdir is used
+ */
+function resolveSystemBuilderParentDir(systemDir, homeDir) {
+  const s = path.resolve(systemDir);
+  const h = path.resolve(homeDir);
+  const rel = path.relative(h, s);
+  const configUnderHome = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  return configUnderHome ? s : h;
+}
+
+module.exports = {
+  resolveSystemBuilderParentDir
+};

package/lib/utils/url-declarative-resolve-build.js

@@ -19,6 +19,7 @@ const {
 const { computePathActive } = require('./url-declarative-url-flags');
 const { loadApplicationYamlDocForUrlResolve } = require('./url-declarative-resolve-load-doc');
 const { parseUrlToken } = require('./url-declarative-token-parse');
+const runtimeBasePath = require('./url-declarative-runtime-base-path');
 
 /**
  * Plan 122: **Developer subdomain `devNN` + remote hostname is not derived from envKey `tst`.** It comes only from
@@ -209,6 +210,7 @@ function buildInternalUrlString(opts) {
     profile,
     listenPort,
     targetAppKey,
+    runtimeBasePath,
     remoteServer,
     pathPrefix,
     patternPath,
@@ -223,7 +225,8 @@ function buildInternalUrlString(opts) {
     declarativeCurrentAppKey
   } = opts;
   if (profile === 'docker') {
-    return `http://${targetAppKey}:${listenPort}`;
+    const origin = `http://${targetAppKey}:${listenPort}`;
+    return runtimeBasePath ? joinUrlPath(origin, runtimeBasePath) : origin;
   }
   if (remoteServer && String(remoteServer).trim()) {
     return buildPublicUrlString({
@@ -432,10 +435,12 @@ function expandFullSurfaceInternal(r) {
   if (isLocalProfileWithoutRemoteServer(r)) {
     return expandFullSurfacePublic(r);
   }
+  const runtimePath = runtimeBasePath.normalizeRuntimeBasePath(r.patternPath, r);
   return buildInternalUrlString({
     profile: r.profile,
     listenPort: r.listenPort,
     targetAppKey: r.appKey,
+    runtimeBasePath: runtimePath,
     remoteServer: r.remoteServer,
     pathPrefix: r.pathPrefix,
     patternPath: r.patternPath,

package/lib/utils/url-declarative-runtime-base-path.js

@@ -0,0 +1,32 @@
+/**
+ * Runtime base path helpers for declarative url:// resolution.
+ *
+ * @fileoverview Keeps path-aware internal URLs out of the main resolver file.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Runtime base path is derived from the existing frontDoorRouting path only
+ * when that path is active for the target app.
+ * @param {string|null|undefined} patternPath
+ * @param {Object} r
+ * @returns {string}
+ */
+function normalizeRuntimeBasePath(patternPath, r) {
+  if (!r.frontDoorIngressActive) {
+    return '';
+  }
+  const value = String(patternPath || '').trim();
+  if (!value || value === '/') {
+    return '';
+  }
+  const pathValue = value.startsWith('/') ? value : `/${value}`;
+  return pathValue.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+}
+
+module.exports = {
+  normalizeRuntimeBasePath
+};

package/lib/utils/url-declarative-vdir-inactive-env.js

@@ -95,5 +95,6 @@ module.exports = {
   URL_DECLARATIVE_VDIR_PUBLIC_TOKEN,
   INACTIVE_VDIR_PUBLIC_ENV_FALLBACK,
   applyInactiveVdirPublicTokenRewrite,
-  rewriteInactiveDeclarativeVdirPublicContent
+  rewriteInactiveDeclarativeVdirPublicContent,
+  isFrontDoorRoutingEnabledInDoc
 };

package/lib/utils/urls-local-registry.js

@@ -1,7 +1,6 @@
 /**
- * urls.local.yaml beside effective config.yaml (same directory as secrets.local.yaml).
- * When AIFABRIX_HOME is POSIX $HOME but config lives in $HOME/.aifabrix/, the registry
- * is $HOME/.aifabrix/urls.local.yaml (not $HOME/urls.local.yaml).
+ * Primary `urls.local.yaml` under {@link module:lib/utils/paths.getAifabrixHome} (same as
+ * `secrets.local.yaml`). When that file is missing, falls back to the config directory for migration.
  *
  * @fileoverview Read/write registry; scan each builder app folder for application.yaml
  * @author AI Fabrix Team
@@ -17,15 +16,15 @@ const { DECLARATIVE_URL_INFRA_DEFAULTS } = require('./infra-env-defaults');
 const pathsUtil = require('./paths');
 
 /**
- * @returns {string} Absolute path to urls.local.yaml (primary; beside config.yaml)
+ * @returns {string} Absolute path to urls.local.yaml (primary; under resolved AI Fabrix home)
  */
 function getUrlsLocalYamlPath() {
-  return path.join(pathsUtil.getConfigDirForPaths(), 'urls.local.yaml');
+  return path.join(pathsUtil.getAifabrixHome(), 'urls.local.yaml');
 }
 
-/** @returns {string} Legacy path when registry was stored under getAifabrixHome() only */
-function getLegacyUrlsLocalYamlPath() {
-  return path.join(pathsUtil.getAifabrixHome(), 'urls.local.yaml');
+/** @returns {string} Path beside config.yaml (migration / older layouts) */
+function getConfigDirUrlsLocalYamlPath() {
+  return path.join(pathsUtil.getConfigDirForPaths(), 'urls.local.yaml');
 }
 
 function loadRegistryYamlFile(filePath) {
@@ -45,9 +44,9 @@ function readUrlsLocalRegistrySync() {
   if (fsRealSync.existsSync(primary)) {
     return loadRegistryYamlFile(primary);
   }
-  const legacy = getLegacyUrlsLocalYamlPath();
-  if (legacy !== primary && fsRealSync.existsSync(legacy)) {
-    return loadRegistryYamlFile(legacy);
+  const atConfig = getConfigDirUrlsLocalYamlPath();
+  if (path.resolve(atConfig) !== path.resolve(primary) && fsRealSync.existsSync(atConfig)) {
+    return loadRegistryYamlFile(atConfig);
   }
   return {};
 }
@@ -242,7 +241,19 @@ function refreshUrlsLocalRegistryFromBuilder(projectRoot) {
   } catch {
     effectiveBuilderDir = null;
   }
-  const builderDirs = getOrderedBuilderDirsForRegistryScan(root, effectiveBuilderDir);
+  let builderDirs = getOrderedBuilderDirsForRegistryScan(root, effectiveBuilderDir);
+  try {
+    const sysRoot = pathsUtil.getSystemBuilderRoot();
+    const resolvedSys = path.resolve(sysRoot);
+    if (fsRealSync.existsSync(sysRoot)) {
+      const resolvedList = builderDirs.map((d) => path.resolve(d));
+      if (!resolvedList.includes(resolvedSys)) {
+        builderDirs = [sysRoot, ...builderDirs];
+      }
+    }
+  } catch {
+    // ignore
+  }
   for (const builderDir of builderDirs) {
     mergeBuilderDirIntoRegistry(merged, builderDir);
   }

package/lib/utils/validation-poll-ui.js

@@ -0,0 +1,81 @@
+/**
+ * TTY ora spinner + throttled non-TTY lines for unified validation run polling (aligned with deploy-poll-ui).
+ *
+ * @fileoverview Validation run poll presentation helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+function shouldUseValidationPollSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * Single-line ora text / log line for validation polling.
+ *
+ * @param {Object|null|undefined} envelope - Latest GET envelope (optional before first poll tick)
+ * @param {number} attemptIndex - Zero-based poll index after initial POST
+ * @param {number} deadlineMs - Wall-clock deadline (Date.now() + remaining budget)
+ * @returns {string}
+ */
+function buildValidationPollSpinnerText(envelope, attemptIndex, deadlineMs) {
+  const remainingSec = Math.max(0, Math.ceil((deadlineMs - Date.now()) / 1000));
+  if (!envelope || typeof envelope !== 'object') {
+    return `Waiting for validation run… starting (budget ~${remainingSec}s)`;
+  }
+  const c =
+    envelope.reportCompleteness !== undefined && envelope.reportCompleteness !== null
+      ? String(envelope.reportCompleteness)
+      : '?';
+  const st =
+    envelope.status !== undefined && envelope.status !== null ? String(envelope.status) : '?';
+  return `Waiting for validation run… completeness=${c} status=${st} (poll ${attemptIndex + 1} · ~${remainingSec}s left)`;
+}
+
+const NON_TTY_THROTTLE_MS = 5000;
+
+/**
+ * @param {number} deadlineMs - Absolute deadline for poll budget display
+ * @returns {{ usesSpinner: boolean, onPollProgress: Function, finish: () => void }}
+ */
+function createValidationPollHandlers(deadlineMs) {
+  if (shouldUseValidationPollSpinner()) {
+    const ora = require('ora');
+    const spinner = ora({
+      text: buildValidationPollSpinnerText(null, 0, deadlineMs),
+      spinner: 'dots'
+    }).start();
+    return {
+      usesSpinner: true,
+      onPollProgress: (envelope, attemptIndex, _meta) => {
+        spinner.text = buildValidationPollSpinnerText(envelope, attemptIndex, deadlineMs);
+      },
+      finish: () => {
+        spinner.stop();
+      }
+    };
+  }
+
+  let lastNonTtyLogAt = 0;
+  return {
+    usesSpinner: false,
+    onPollProgress: (envelope, attemptIndex, _meta) => {
+      const now = Date.now();
+      if (now - lastNonTtyLogAt < NON_TTY_THROTTLE_MS) return;
+      lastNonTtyLogAt = now;
+      logger.log(chalk.gray(buildValidationPollSpinnerText(envelope, attemptIndex, deadlineMs)));
+    },
+    finish: () => {}
+  };
+}
+
+module.exports = {
+  createValidationPollHandlers,
+  shouldUseValidationPollSpinner,
+  buildValidationPollSpinnerText
+};