@aifabrix/builder 2.45.0 → 2.46.0

package/lib/utils/secrets-missing-error.js

@@ -0,0 +1,164 @@
+/**
+ * Build missing-secrets errors with remediation hints (no secret values).
+ *
+ * @fileoverview Missing kv:// error message for resolve and env generation
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { formatMissingSecretsFileInfo } = require('./secrets-helpers');
+
+/**
+ * @param {string} line
+ * @returns {boolean}
+ */
+function isCommentOrEmptyLine(line) {
+  const t = String(line).trim();
+  return t === '' || t.startsWith('#');
+}
+
+/**
+ * @param {string} kvRef - e.g. kv://hubspot-demo/clientSecret
+ * @returns {string}
+ */
+function kvRefToSecretSetKey(kvRef) {
+  const s = String(kvRef || '').trim();
+  return s.replace(/^kv:\/\//i, '');
+}
+
+/**
+ * @param {string} envTemplate
+ * @param {string} kvRef
+ * @returns {string|null}
+ */
+function findActiveEnvLineForKvRef(envTemplate, kvRef) {
+  if (!envTemplate || !kvRef) return null;
+  const needle = String(kvRef).trim();
+  for (const line of envTemplate.split('\n')) {
+    if (isCommentOrEmptyLine(line)) continue;
+    if (line.includes(needle)) return line.trim();
+  }
+  return null;
+}
+
+const OAUTH_STALE_KV_PATH_RE = /\/(clientId|clientSecret|tokenUrl|authorizationUrl)$/i;
+
+/**
+ * @param {string[]} missing
+ * @returns {boolean}
+ */
+function hasStaleOAuthTemplatePaths(missing) {
+  return missing.some((ref) => OAUTH_STALE_KV_PATH_RE.test(String(ref)));
+}
+
+/**
+ * @param {string} key
+ * @param {Object} secrets
+ * @returns {boolean}
+ */
+function isPopulatedSecretKey(key, secrets) {
+  const value = secrets[key];
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+/**
+ * Other populated secret paths that share the same path segment after the namespace.
+ *
+ * @param {string} pathStr - Secret path without kv:// (e.g. my-app-e2e/clientId)
+ * @param {Object} secrets
+ * @returns {string[]}
+ */
+function findPopulatedAlternateKvPaths(pathStr, secrets) {
+  if (!secrets || typeof secrets !== 'object' || !pathStr) {
+    return [];
+  }
+  const slash = pathStr.indexOf('/');
+  if (slash <= 0) {
+    return [];
+  }
+  const missingNamespace = pathStr.slice(0, slash);
+  const segment = pathStr.slice(slash + 1);
+  return Object.keys(secrets).filter((key) => {
+    if (typeof key !== 'string' || !key.includes('/')) {
+      return false;
+    }
+    const keySlash = key.indexOf('/');
+    const namespace = key.slice(0, keySlash);
+    const keySegment = key.slice(keySlash + 1);
+    return (
+      keySegment === segment &&
+      namespace !== missingNamespace &&
+      isPopulatedSecretKey(key, secrets)
+    );
+  });
+}
+
+/**
+ * @param {string[]} missing - kv:// refs
+ * @param {Object} [secrets]
+ * @param {string} [appName]
+ * @returns {string[]}
+ */
+function buildKvNamespaceAlternateHints(missing, secrets, appName) {
+  const lines = [];
+  const seen = new Set();
+  for (const ref of missing) {
+    const pathStr = kvRefToSecretSetKey(ref);
+    for (const alt of findPopulatedAlternateKvPaths(pathStr, secrets)) {
+      const line = `Found kv://${alt} in secrets; env.template references kv://${pathStr}.`;
+      if (seen.has(line)) {
+        continue;
+      }
+      seen.add(line);
+      lines.push(line);
+    }
+  }
+  if (lines.length === 0) {
+    return [];
+  }
+  const repairTail = appName
+    ? `Use aifabrix secret set <key> for each missing path, or aifabrix repair ${appName} to align env.template.`
+    : 'Use aifabrix secret set <key> for each missing path, or repair to align env.template.';
+  lines.push(repairTail);
+  return lines;
+}
+
+/**
+ * @param {Object} opts
+ * @param {string[]} opts.missing
+ * @param {Object|string|null} [opts.secretsFilePaths]
+ * @param {string} [opts.appName]
+ * @param {string} [opts.envTemplatePath]
+ * @param {string} [opts.envTemplate]
+ * @param {Object} [opts.secrets]
+ * @returns {string}
+ */
+function buildMissingSecretsErrorMessage(opts) {
+  const { missing, secretsFilePaths, appName, envTemplatePath, envTemplate, secrets } = opts;
+  const fileInfo = formatMissingSecretsFileInfo(secretsFilePaths);
+  const lines = [`Missing secrets: ${missing.join(', ')}`];
+  if (fileInfo) lines.push(fileInfo.trim());
+  if (envTemplatePath) lines.push(`Env-template-path: ${envTemplatePath}`);
+  for (const ref of missing) {
+    const templateLine = findActiveEnvLineForKvRef(envTemplate, ref);
+    if (templateLine) lines.push(`Env-template-line: ${ref}|${templateLine}`);
+  }
+  if (appName) lines.push(`App-name: ${appName}`);
+  if (hasStaleOAuthTemplatePaths(missing) && appName) {
+    lines.push(`Stale-template-hint: oauth-leftover | repair ${appName}`);
+  }
+  for (const hint of buildKvNamespaceAlternateHints(missing, secrets, appName)) {
+    lines.push(`Alternate-kv-hint: ${hint}`);
+  }
+  lines.push('Remediation-hint: comment-or-delete-template-line | secret-set');
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  kvRefToSecretSetKey,
+  findActiveEnvLineForKvRef,
+  findPopulatedAlternateKvPaths,
+  buildMissingSecretsErrorMessage
+};

package/lib/utils/semver-compare.js

@@ -0,0 +1,127 @@
+/**
+ * Internal semver comparator (no `semver` npm dependency).
+ *
+ * Supports `MAJOR.MINOR.PATCH` and optional prerelease suffix
+ * `-<prerelease>` (e.g. `2.45.0-beta.1`). Optional leading `v` is tolerated.
+ * Prerelease versions always rank **before** the same MAJOR.MINOR.PATCH
+ * without a prerelease (semver §11.3).
+ *
+ * @fileoverview Internal semver compare for Builder CLI compatibility gate
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const SEMVER_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z][-0-9A-Za-z.]*))?$/;
+
+/**
+ * Parse a semver-like string into a comparable structure.
+ * @param {string} input - Version string (e.g. "2.45.0" or "v2.45.0-beta.1")
+ * @returns {{ major:number, minor:number, patch:number, prerelease:string[] }|null}
+ *          Parsed parts or null when input does not match the supported grammar
+ */
+function parseSemver(input) {
+  if (typeof input !== 'string') {
+    return null;
+  }
+  const match = SEMVER_PATTERN.exec(input.trim());
+  if (!match) {
+    return null;
+  }
+  const [, major, minor, patch, prerelease] = match;
+  return {
+    major: Number(major),
+    minor: Number(minor),
+    patch: Number(patch),
+    prerelease: prerelease ? prerelease.split('.') : []
+  };
+}
+
+/**
+ * Check whether a string is a supported semver (incl. optional prerelease).
+ * @param {string} input
+ * @returns {boolean}
+ */
+function isValidSemver(input) {
+  return parseSemver(input) !== null;
+}
+
+/**
+ * Compare two prerelease identifier arrays per semver §11.4.
+ * @private
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {-1|0|1}
+ */
+function comparePrereleaseIds(a, b) {
+  const len = Math.max(a.length, b.length);
+  for (let i = 0; i < len; i += 1) {
+    if (a[i] === undefined) return -1;
+    if (b[i] === undefined) return 1;
+    const aNum = /^\d+$/.test(a[i]);
+    const bNum = /^\d+$/.test(b[i]);
+    if (aNum && bNum) {
+      const diff = Number(a[i]) - Number(b[i]);
+      if (diff !== 0) return diff > 0 ? 1 : -1;
+    } else if (aNum) {
+      return -1;
+    } else if (bNum) {
+      return 1;
+    } else if (a[i] !== b[i]) {
+      return a[i] > b[i] ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Compare two semver strings.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1}  `-1` when `a < b`, `0` when equal, `1` when `a > b`
+ * @throws {Error} When either argument is not a valid semver
+ *
+ * @example
+ *   compareSemver('2.44.0', '2.45.0') === -1
+ *   compareSemver('2.45.0', '2.45.0') === 0
+ *   compareSemver('2.45.0-beta.1', '2.45.0') === -1
+ */
+function compareSemver(a, b) {
+  const parsedA = parseSemver(a);
+  const parsedB = parseSemver(b);
+  if (!parsedA) throw new Error(`Invalid semver: "${a}"`);
+  if (!parsedB) throw new Error(`Invalid semver: "${b}"`);
+
+  if (parsedA.major !== parsedB.major) return parsedA.major > parsedB.major ? 1 : -1;
+  if (parsedA.minor !== parsedB.minor) return parsedA.minor > parsedB.minor ? 1 : -1;
+  if (parsedA.patch !== parsedB.patch) return parsedA.patch > parsedB.patch ? 1 : -1;
+
+  // §11.3 — Prerelease has lower precedence than the same MAJOR.MINOR.PATCH release.
+  if (parsedA.prerelease.length === 0 && parsedB.prerelease.length === 0) return 0;
+  if (parsedA.prerelease.length === 0) return 1;
+  if (parsedB.prerelease.length === 0) return -1;
+
+  return comparePrereleaseIds(parsedA.prerelease, parsedB.prerelease);
+}
+
+/**
+ * Convenience: true when `current >= required`.
+ * Returns `true` when `required` is empty/null/undefined (no enforcement).
+ * @param {string} current
+ * @param {string} [required]
+ * @returns {boolean}
+ * @throws {Error} If either provided value is not valid semver
+ */
+function isAtLeast(current, required) {
+  if (required === undefined || required === null || required === '') return true;
+  return compareSemver(current, required) >= 0;
+}
+
+module.exports = {
+  parseSemver,
+  isValidSemver,
+  compareSemver,
+  isAtLeast
+};

package/lib/utils/service-url-label.js

@@ -0,0 +1,81 @@
+/**
+ * Infer which platform service a request URL targets (CLI error copy).
+ *
+ * @fileoverview Service label heuristics for network error messages
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {readonly string[]} */
+const DATAPLANE_PATH_PREFIXES = Object.freeze([
+  '/api/v1/external',
+  '/api/v1/validation',
+  '/api/v1/records',
+  '/api/v1/wizard',
+  '/api/v1/admin',
+  '/api/v1/health',
+  '/api/v1/dataplane',
+  '/api/v1/policy',
+  '/api/v1/mcp',
+  '/api/v1/ide',
+  '/api/v1/knowledgebase'
+]);
+
+/** @type {readonly string[]} */
+const CONTROLLER_PATH_PREFIXES = Object.freeze([
+  '/api/v1/auth',
+  '/api/v1/applications',
+  '/api/v1/pipeline',
+  '/api/v1/environments',
+  '/api/v1/deployments',
+  '/api/v1/datasources',
+  '/api/v1/external-systems',
+  '/api/controller'
+]);
+
+/**
+ * @param {string} url - Full request URL
+ * @returns {'dataplane'|'controller'|'service'}
+ */
+function inferServiceLabelFromUrl(url) {
+  if (!url || typeof url !== 'string') {
+    return 'service';
+  }
+  try {
+    const path = new URL(url.trim()).pathname || '';
+    for (const prefix of DATAPLANE_PATH_PREFIXES) {
+      if (path.startsWith(prefix)) {
+        return 'dataplane';
+      }
+    }
+    for (const prefix of CONTROLLER_PATH_PREFIXES) {
+      if (path.startsWith(prefix)) {
+        return 'controller';
+      }
+    }
+  } catch {
+    return 'service';
+  }
+  return 'service';
+}
+
+/**
+ * @param {'dataplane'|'controller'|'service'} label
+ * @returns {string}
+ */
+function serviceLabelDisplayName(label) {
+  if (label === 'dataplane') {
+    return 'dataplane';
+  }
+  if (label === 'controller') {
+    return 'controller';
+  }
+  return 'service';
+}
+
+module.exports = {
+  inferServiceLabelFromUrl,
+  serviceLabelDisplayName
+};

package/lib/utils/setup-quiet-output.js

@@ -0,0 +1,25 @@
+/**
+ * Suppress verbose CLI detail during `aifabrix setup` (guided milestones only).
+ *
+ * @fileoverview Setup quiet output flag
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @returns {boolean} True while `aifabrix setup` is running
+ */
+function isSetupQuietOutput() {
+  try {
+    const { isSetupCommandFlow } = require('../commands/setup-run-context');
+    return isSetupCommandFlow();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  isSetupQuietOutput
+};

package/lib/utils/template-helpers.js

@@ -110,6 +110,20 @@ function updateDatabaseConfig(variables, options, appName) {
  * @param {Object} options - CLI options
  * @param {Object} config - Final configuration
  */
+async function patchEnvTemplateRelativePathKey(appPath, appName) {
+  const fsSync = require('fs');
+  const envTemplatePath = path.join(appPath, 'env.template');
+  if (!fsSync.existsSync(envTemplatePath)) {
+    return;
+  }
+  const { renameAppRelativePathEnvKeyInTemplate } = require('./app-relative-path-env');
+  const raw = await fs.readFile(envTemplatePath, 'utf8');
+  const patched = renameAppRelativePathEnvKeyInTemplate(raw, appName);
+  if (patched !== raw) {
+    await fs.writeFile(envTemplatePath, patched, 'utf8');
+  }
+}
+
 async function updateTemplateVariables(appPath, appName, options, config) {
   const { resolveApplicationConfigPath } = require('./app-config-resolver');
   const { loadConfigFile, writeConfigFile } = require('./config-format');
@@ -123,6 +137,7 @@ async function updateTemplateVariables(appPath, appName, options, config) {
     updateDatabaseConfig(variables, options, appName);
 
     writeConfigFile(variablesPath, variables);
+    await patchEnvTemplateRelativePathKey(appPath, appName);
   } catch (error) {
     if (error.message && !error.message.includes('not found')) {
       logger.warn(chalk.yellow(`⚠  Warning: Could not update application config: ${error.message}`));

package/lib/utils/token-manager-client-credentials.js

@@ -0,0 +1,201 @@
+/**
+ * Client credential loading from secrets.local.yaml and environment.
+ *
+ * @fileoverview Client credentials helpers for token-manager
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+const logger = require('./logger');
+const pathsUtil = require('./paths');
+
+/** App key used for dataplane client credentials in secrets.local.yaml */
+const DATAPLANE_APP_KEY = 'dataplane';
+
+/**
+ * @returns {string}
+ */
+function getSecretsFilePath() {
+  return pathsUtil.getPrimaryUserSecretsLocalPath();
+}
+
+/**
+ * Validate that secrets.local.yaml contains dataplane client credentials.
+ * @param {string} [secretsFilePath] - Path to secrets file; defaults to ~/.aifabrix/secrets.local.yaml
+ * @returns {{ valid: boolean, hint?: string }}
+ */
+function validateDataplaneSecrets(secretsFilePath) {
+  const filePath = secretsFilePath || getSecretsFilePath();
+  const hint = 'Dataplane credentials are missing. Run: aifabrix app rotate-secret dataplane';
+  try {
+    if (!fs.existsSync(filePath)) {
+      return { valid: false, hint };
+    }
+    const content = fs.readFileSync(filePath, 'utf8');
+    const secrets = yaml.load(content) || {};
+    const clientIdKey = `${DATAPLANE_APP_KEY}-client-idKeyVault`;
+    const clientSecretKey = `${DATAPLANE_APP_KEY}-client-secretKeyVault`;
+    const hasId =
+      secrets[clientIdKey] !== null &&
+      secrets[clientIdKey] !== undefined &&
+      String(secrets[clientIdKey]).trim() !== '';
+    const hasSecret =
+      secrets[clientSecretKey] !== null &&
+      secrets[clientSecretKey] !== undefined &&
+      String(secrets[clientSecretKey]).trim() !== '';
+    if (hasId && hasSecret) {
+      return { valid: true };
+    }
+    return { valid: false, hint };
+  } catch {
+    return { valid: false, hint };
+  }
+}
+
+/**
+ * Read client id/secret for one app key from secrets.local.yaml.
+ * @param {string} appName - Application key
+ * @returns {{ clientId: string, clientSecret: string }|null}
+ */
+function readClientCredentialsFromSecretsFile(appName) {
+  try {
+    const secretsFile = getSecretsFilePath();
+    if (!fs.existsSync(secretsFile)) {
+      return null;
+    }
+    const content = fs.readFileSync(secretsFile, 'utf8');
+    const secrets = yaml.load(content) || {};
+    const clientId = secrets[`${appName}-client-idKeyVault`];
+    const clientSecret = secrets[`${appName}-client-secretKeyVault`];
+    if (clientId && clientSecret) {
+      return {
+        clientId: String(clientId),
+        clientSecret: String(clientSecret)
+      };
+    }
+  } catch (error) {
+    logger.warn(`Failed to load credentials from secrets.local.yaml: ${error.message}`);
+  }
+  return null;
+}
+
+/**
+ * App keys to try when resolving client credentials (integration app, then dataplane).
+ * @param {string} appName
+ * @returns {string[]}
+ */
+function credentialAppKeysToTry(appName) {
+  const keys = [appName];
+  if (appName !== DATAPLANE_APP_KEY) {
+    keys.push(DATAPLANE_APP_KEY);
+  }
+  return keys;
+}
+
+/**
+ * @returns {{ clientId: string, clientSecret: string }|null}
+ */
+function readClientCredentialsFromEnv() {
+  const pairs = [
+    [process.env.CLIENTID || process.env.CLIENT_ID, process.env.CLIENTSECRET || process.env.CLIENT_SECRET],
+    [
+      process.env.MISO_CLIENTID || process.env.MISO_CLIENT_ID,
+      process.env.MISO_CLIENTSECRET || process.env.MISO_CLIENT_SECRET
+    ]
+  ];
+  for (const [clientId, clientSecret] of pairs) {
+    if (clientId && clientSecret) {
+      return {
+        clientId: String(clientId).trim(),
+        clientSecret: String(clientSecret).trim()
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Decrypt secure:// client credential entries from secrets.local.yaml when needed.
+ * @param {string} appName
+ * @param {{ clientId: string, clientSecret: string }} raw
+ * @returns {Promise<{ clientId: string, clientSecret: string }|null>}
+ */
+async function decryptClientCredentialsFromSecrets(appName, raw) {
+  const { isEncrypted } = require('./secrets-encryption');
+  if (!isEncrypted(raw.clientId) && !isEncrypted(raw.clientSecret)) {
+    return raw;
+  }
+  try {
+    const { decryptSecretsObject } = require('../core/secrets-load');
+    const idKey = `${appName}-client-idKeyVault`;
+    const secretKey = `${appName}-client-secretKeyVault`;
+    const decrypted = await decryptSecretsObject({
+      [idKey]: raw.clientId,
+      [secretKey]: raw.clientSecret
+    });
+    const clientId = decrypted[idKey];
+    const clientSecret = decrypted[secretKey];
+    if (clientId && clientSecret) {
+      return {
+        clientId: String(clientId),
+        clientSecret: String(clientSecret)
+      };
+    }
+  } catch (error) {
+    logger.warn(`Failed to decrypt client credentials for ${appName}: ${error.message}`);
+  }
+  return null;
+}
+
+/**
+ * @param {string} appName
+ * @returns {Promise<{ clientId: string, clientSecret: string }|null>}
+ */
+async function readClientCredentialsFromSecretsFileDecrypted(appName) {
+  const raw = readClientCredentialsFromSecretsFile(appName);
+  if (!raw) {
+    return null;
+  }
+  return decryptClientCredentialsFromSecrets(appName, raw);
+}
+
+/**
+ * @param {string} appName
+ * @returns {Promise<{ credentialApp: string, credentials: { clientId: string, clientSecret: string }|null }>}
+ */
+async function resolveCredentialAppForDeployment(appName) {
+  const fromEnv = readClientCredentialsFromEnv();
+  if (fromEnv) {
+    return { credentialApp: appName, credentials: fromEnv };
+  }
+  for (const key of credentialAppKeysToTry(appName)) {
+    const fromFile = await readClientCredentialsFromSecretsFileDecrypted(key);
+    if (fromFile) {
+      return { credentialApp: key, credentials: fromFile };
+    }
+  }
+  return { credentialApp: appName, credentials: null };
+}
+
+/**
+ * @param {string} appName
+ * @returns {Promise<{ clientId: string, clientSecret: string }|null>}
+ */
+async function loadClientCredentials(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  const resolved = await resolveCredentialAppForDeployment(appName);
+  return resolved.credentials;
+}
+
+module.exports = {
+  DATAPLANE_APP_KEY,
+  validateDataplaneSecrets,
+  loadClientCredentials,
+  resolveCredentialAppForDeployment
+};

package/lib/utils/token-manager-messages.js

@@ -39,6 +39,10 @@ function resetRefreshWarnedUrlsForTesting() {
  * @param {string} errorMessage - Full error message to log
  */
 function warnRefreshTokenExpiredOnce(controllerUrl, errorMessage) {
+  const { isSetupPlatformFlow } = require('../commands/setup-run-context');
+  if (isSetupPlatformFlow()) {
+    return;
+  }
   const key = (controllerUrl && typeof controllerUrl === 'string' && controllerUrl.trim())
     ? config.normalizeControllerUrl(controllerUrl)
     : '__no_url__';
@@ -72,6 +76,10 @@ function formatRefreshFailureMessage(errorMessage, controllerUrl) {
  * @param {string} errorMessage - Raw error message
  */
 function warnRefreshFailureOnce(controllerUrl, errorMessage) {
+  const { isSetupPlatformFlow } = require('../commands/setup-run-context');
+  if (isSetupPlatformFlow()) {
+    return;
+  }
   const key = (controllerUrl && typeof controllerUrl === 'string' && controllerUrl.trim())
     ? config.normalizeControllerUrl(controllerUrl)
     : '__no_url__';

package/lib/utils/token-manager-refresh.js

@@ -79,11 +79,21 @@ async function callTokenApi(controllerUrl, credentials) {
   }
 
   const responseData = response.data;
-  if (!responseData || !responseData.token) {
+  const token =
+    responseData?.token ||
+    responseData?.data?.token ||
+    responseData?.data?.data?.token ||
+    responseData?.accessToken;
+  if (!token) {
     throw new Error('Invalid response: missing token');
   }
 
-  return responseData;
+  return {
+    ...responseData,
+    token,
+    expiresIn: responseData.expiresIn ?? responseData.data?.expiresIn,
+    expiresAt: responseData.expiresAt ?? responseData.data?.expiresAt
+  };
 }
 
 /**