@aifabrix/builder 2.40.2 → 2.42.0

package/lib/utils/secrets-helpers.js

@@ -18,6 +18,7 @@ const { loadEnvConfig } = require('./env-config-loader');
 const { updateContainerPortInEnvFile } = require('./env-ports');
 const { buildEnvVarMap } = require('./env-map');
 const { getLocalPortFromPath } = require('./port-resolver');
+const { readYamlAtPath, applyCanonicalSecretsOverride } = require('./secrets-canonical');
 
 /**
  * Interpolate ${VAR} occurrences with values from envVars map
@@ -42,25 +43,84 @@ function isCommentOrEmptyLine(line) {
   return t === '' || t.startsWith('#');
 }
 
+/** Regex for kv:// path (allows slashes, e.g. kv://hubspot/clientId) */
+const KV_REF_PATTERN = /kv:\/\/([a-zA-Z0-9_\-/]+)/g;
+
+/**
+ * Find object key that matches part case-insensitively.
+ * @param {Object} obj - Object to search
+ * @param {string} part - Key to match (e.g. 'clientid')
+ * @returns {string|undefined} Actual key in obj or undefined
+ */
+function findKeyCaseInsensitive(obj, part) {
+  if (!obj || typeof obj !== 'object' || part === null || part === undefined) return undefined;
+  const lower = String(part).toLowerCase();
+  for (const key of Object.keys(obj)) {
+    if (key.toLowerCase() === lower) return key;
+  }
+  return undefined;
+}
+
 /**
- * Collect missing kv:// secrets referenced in content (skips commented and empty lines)
+ * Resolve value by walking path parts (nested keys).
+ * @param {Object} secrets - Root secrets object
+ * @param {string[]} parts - Path parts (e.g. ['hubspot', 'clientId'])
+ * @returns {*} Value or undefined
+ */
+function getValueByNestedPath(secrets, parts) {
+  let value = secrets;
+  for (const part of parts) {
+    if (!value || typeof value !== 'object') return undefined;
+    const key = part in value ? part : findKeyCaseInsensitive(value, part);
+    value = key !== undefined ? value[key] : undefined;
+    if (value === undefined) return undefined;
+  }
+  return value;
+}
+
+/**
+ * Get secret value by path. Supports flat key (hubspot/clientId), nested object (hubspot.clientId),
+ * and case-insensitive matching (clientid matches clientId). Path-style and hyphen-style are distinct:
+ * hubspot/clientid and hubspot-clientid are different keys.
+ * @param {Object} secrets - Secrets object (may be nested)
+ * @param {string} pathStr - Path after kv:// (e.g. 'hubspot/clientId' or 'hubspot/clientid')
+ * @returns {*} Value or undefined if not found
+ */
+function getValueByPath(secrets, pathStr) {
+  if (!secrets || typeof secrets !== 'object' || !pathStr) {
+    return undefined;
+  }
+  const direct = secrets[pathStr];
+  if (direct !== undefined) return direct;
+  const flatKey = findKeyCaseInsensitive(secrets, pathStr);
+  if (flatKey !== undefined) return secrets[flatKey];
+  if (!pathStr.includes('/')) return undefined;
+  return getValueByNestedPath(secrets, pathStr.split('/'));
+}
+
+/**
+ * Collect missing kv:// secrets referenced in content (skips commented and empty lines).
+ * Supports path-style refs (e.g. kv://hubspot/clientId). Returns unique refs.
  * @function collectMissingSecrets
  * @param {string} content - Text content
- * @param {Object} secrets - Available secrets
- * @returns {string[]} Array of missing kv://<key> references
+ * @param {Object} secrets - Available secrets (flat or nested)
+ * @returns {string[]} Array of missing kv://<path> references (unique)
  */
 function collectMissingSecrets(content, secrets) {
-  const kvPattern = /kv:\/\/([a-zA-Z0-9-_]+)/g;
+  const seen = new Set();
   const missing = [];
   const lines = content.split('\n');
   for (const line of lines) {
     if (isCommentOrEmptyLine(line)) continue;
     let match;
-    kvPattern.lastIndex = 0;
-    while ((match = kvPattern.exec(line)) !== null) {
-      const secretKey = match[1];
-      if (!(secretKey in secrets)) {
-        missing.push(`kv://${secretKey}`);
+    KV_REF_PATTERN.lastIndex = 0;
+    while ((match = KV_REF_PATTERN.exec(line)) !== null) {
+      const pathStr = match[1];
+      if (seen.has(pathStr)) continue;
+      seen.add(pathStr);
+      const value = getValueByPath(secrets, pathStr);
+      if (value === undefined || value === null) {
+        missing.push(`kv://${pathStr}`);
       }
     }
   }
@@ -91,26 +151,26 @@ function formatMissingSecretsFileInfo(secretsFilePaths) {
 }
 
 /**
- * Replace kv:// references with actual values (skips commented and empty lines)
+ * Replace kv:// references with actual values (skips commented and empty lines).
+ * Supports path-style refs (e.g. kv://hubspot/clientId) and nested secrets.
  * @function replaceKvInContent
  * @param {string} content - Text content containing kv:// references
- * @param {Object} secrets - Secrets map
+ * @param {Object} secrets - Secrets map (flat or nested)
  * @param {Object} envVars - Environment variables map for nested interpolation
  * @returns {string} Content with kv:// references replaced
  */
 function replaceKvInContent(content, secrets, envVars) {
-  const kvPattern = /kv:\/\/([a-zA-Z0-9-_]+)/g;
   const lines = content.split('\n');
   const result = lines.map(line => {
     if (isCommentOrEmptyLine(line)) return line;
-    return line.replace(kvPattern, (match, secretKey) => {
-      let value = secrets[secretKey];
+    return line.replace(KV_REF_PATTERN, (match, pathStr) => {
+      let value = getValueByPath(secrets, pathStr);
       if (typeof value === 'string') {
         value = value.replace(/\$\{([A-Z_]+)\}/g, (m, envVar) => {
           return envVars[envVar] || m;
         });
       }
-      return value;
+      return value !== null && value !== undefined ? String(value) : match;
     });
   });
   return result.join('\n');
@@ -166,7 +226,7 @@ function getPortFromLocalEnv(localEnv) {
 }
 
 /**
- * Gets port from application config file (build.localPort if positive, else port). Uses port-resolver.
+ * Gets port from application config file (port only). Uses port-resolver.
  * @function getPortFromVariablesFile
  * @param {string} variablesPath - Path to application config
  * @returns {number|null} Port value or null
@@ -199,7 +259,7 @@ function applyDeveloperIdAdjustment(baseAppPort, devIdNum) {
 
 /**
  * Calculate application port following override chain and developer-id adjustment
- * Override chain: env-config.yaml → config.yaml → application.yaml build.localPort → application.yaml port
+ * Override chain: env-config.yaml → config.yaml → application.yaml port
  * @async
  * @function calculateAppPort
  * @param {string} [variablesPath] - Path to application config
@@ -212,7 +272,7 @@ async function calculateAppPort(variablesPath, localEnv, envContent, devIdNum) {
   // Start with env-config value
   let baseAppPort = getPortFromLocalEnv(localEnv);
 
-  // Override with application config → build.localPort (strongest)
+  // Override with application config port (strongest)
   const variablesPort = getPortFromVariablesFile(variablesPath);
   if (variablesPort !== null) {
     baseAppPort = variablesPort;
@@ -247,13 +307,32 @@ function updateLocalhostUrls(content, baseAppPort, appPort) {
 }
 
 /**
- * Adjust infra-related ports in resolved .env content for local environment
- * Only handles PORT variable (other ports handled by interpolation)
- * Follows flow: getEnvHosts() → config.yaml override → application config override → developer-id adjustment
+ * Get the env var name used for PORT in env.template (e.g. PORT=${MISO_PORT} -> MISO_PORT).
+ * Used when generating .env for envOutputPath (local, not reload) so we set that var to localPort.
+ * @param {string} [variablesPath] - Path to application config (env.template lives in same dir)
+ * @returns {string|null} Variable name or null
+ */
+function getPortVarFromEnvTemplatePath(variablesPath) {
+  if (!variablesPath || !fs.existsSync(variablesPath)) return null;
+  const templatePath = path.join(path.dirname(variablesPath), 'env.template');
+  if (!fs.existsSync(templatePath)) return null;
+  try {
+    const content = fs.readFileSync(templatePath, 'utf8');
+    const m = content.match(/^PORT\s*=\s*\$\{([A-Za-z0-9_]+)\}/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Adjust infra-related ports in resolved .env content for local environment.
+ * Own case: when we generate .env for envOutputPath (not reload), we use localPort (application.yaml build.localPort or port).
+ * Sets PORT and the template port var (e.g. MISO_PORT) to localPort so the generated .env is correct for local use.
  * @async
  * @function adjustLocalEnvPortsInContent
  * @param {string} envContent - Resolved .env content
- * @param {string} [variablesPath] - Path to application config (to read build.localPort)
+ * @param {string} [variablesPath] - Path to application config (to read port and template port var)
  * @returns {Promise<string>} Updated content with local ports
  */
 /**
@@ -348,85 +427,16 @@ async function adjustLocalEnvPortsInContent(envContent, variablesPath) {
   updated = await rewriteInfraEndpoints(updated, 'local');
 
   const envVars = await buildEnvVarsForInterpolation(devIdNum);
+  envVars.PORT = String(appPort);
+  const portVar = getPortVarFromEnvTemplatePath(variablesPath);
+  if (portVar) {
+    envVars[portVar] = String(appPort);
+  }
   updated = interpolateEnvVars(updated, envVars);
 
   return updated;
 }
 
-/**
- * Read a YAML file and return parsed object
- * @function readYamlAtPath
- * @param {string} filePath - Absolute file path
- * @returns {Object} Parsed YAML object
- */
-function readYamlAtPath(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
-  return yaml.load(content);
-}
-
-/**
- * Merge a single secret value from canonical into result
- * @function mergeSecretValue
- * @param {Object} result - Result object to merge into
- * @param {string} key - Secret key
- * @param {*} canonicalValue - Value from canonical secrets
- */
-function mergeSecretValue(result, key, canonicalValue) {
-  const currentValue = result[key];
-  // Fill missing, empty, or undefined values
-  if (!(key in result) || currentValue === undefined || currentValue === null || currentValue === '') {
-    result[key] = canonicalValue;
-    return;
-  }
-  // Only replace values that are encrypted (have secure:// prefix)
-  // Plaintext values (no secure://) are used as-is
-  if (typeof currentValue === 'string' && typeof canonicalValue === 'string') {
-    if (currentValue.startsWith('secure://')) {
-      result[key] = canonicalValue;
-    }
-  }
-}
-
-/**
- * Apply canonical secrets path override if configured and file exists
- * @async
- * @function applyCanonicalSecretsOverride
- * @param {Object} currentSecrets - Current secrets map
- * @returns {Promise<Object>} Possibly overridden secrets
- */
-async function applyCanonicalSecretsOverride(currentSecrets) {
-  let mergedSecrets = currentSecrets || {};
-  try {
-    const canonicalPath = await config.getSecretsPath();
-    if (!canonicalPath) {
-      return mergedSecrets;
-    }
-    const resolvedCanonical = path.isAbsolute(canonicalPath)
-      ? canonicalPath
-      : path.resolve(process.cwd(), canonicalPath);
-    if (!fs.existsSync(resolvedCanonical)) {
-      return mergedSecrets;
-    }
-    const configSecrets = readYamlAtPath(resolvedCanonical);
-    if (!configSecrets || typeof configSecrets !== 'object') {
-      return mergedSecrets;
-    }
-    // Apply canonical secrets as a fallback source:
-    // - Do NOT override any existing keys from user/build
-    // - Add only missing keys from canonical path
-    // - Also fill in empty/undefined values from canonical path
-    // - Replace encrypted values (secure://) with canonical plaintext
-    const result = { ...mergedSecrets };
-    for (const [key, canonicalValue] of Object.entries(configSecrets)) {
-      mergeSecretValue(result, key, canonicalValue);
-    }
-    mergedSecrets = result;
-  } catch {
-    // ignore and fall through
-  }
-  return mergedSecrets;
-}
-
 /**
  * Ensure secrets map is non-empty or throw a friendly guidance error
  * @function ensureNonEmptySecrets
@@ -447,24 +457,8 @@ function ensureNonEmptySecrets(secrets) {
  * @returns {Object} Validation result
  */
 function validateSecrets(envTemplate, secrets) {
-  const kvPattern = /kv:\/\/([a-zA-Z0-9-_]+)/g;
-  const missing = [];
-  const lines = envTemplate.split('\n');
-  for (const line of lines) {
-    if (isCommentOrEmptyLine(line)) continue;
-    let match;
-    kvPattern.lastIndex = 0;
-    while ((match = kvPattern.exec(line)) !== null) {
-      const secretKey = match[1];
-      if (!(secretKey in secrets)) {
-        missing.push(`kv://${secretKey}`);
-      }
-    }
-  }
-  return {
-    valid: missing.length === 0,
-    missing
-  };
+  const missing = collectMissingSecrets(envTemplate, secrets);
+  return { valid: missing.length === 0, missing };
 }
 
 module.exports = {

package/lib/utils/secrets-path.js

@@ -54,8 +54,8 @@ async function getActualSecretsPath(secretsPath, _appName) {
     };
   }
 
-  // Cascading lookup: user's file first (under configured home)
-  const userSecretsPath = path.join(paths.getAifabrixHome(), 'secrets.local.yaml');
+  // Cascading lookup: user's file first (primary home: AIFABRIX_HOME or ~/.aifabrix)
+  const userSecretsPath = path.join(paths.getConfigDirForPaths(), 'secrets.local.yaml');
 
   // Check config.yaml for canonical secrets path
   let buildSecretsPath = null;

package/lib/utils/secrets-utils.js

@@ -15,6 +15,24 @@ const yaml = require('js-yaml');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
 const { getContainerPort } = require('./port-resolver');
+const { loadYamlTolerantOfDuplicateKeys } = require('./secrets-generator');
+
+/**
+ * Parses secrets YAML content with fallback for duplicate keys.
+ * @param {string} content - Raw file content
+ * @returns {Object} Parsed secrets object
+ */
+function parseSecretsContent(content) {
+  try {
+    return yaml.load(content);
+  } catch (yamlErr) {
+    const msg = yamlErr.message || '';
+    if (msg.includes('duplicate') || msg.includes('duplicated mapping')) {
+      return loadYamlTolerantOfDuplicateKeys(content);
+    }
+    throw yamlErr;
+  }
+}
 
 /**
  * Loads secrets from file with cascading lookup support
@@ -45,6 +63,38 @@ async function loadSecretsFromFile(filePath) {
   }
 }
 
+/**
+ * Loads user secrets from the primary config directory (AIFABRIX_HOME or ~/.aifabrix).
+ * Used as the master source when merging with project/public secrets: user values win,
+ * missing keys are filled from the public (aifabrix-secrets) file.
+ * Does not use config.yaml aifabrix-home so the merge always sees the actual user file.
+ *
+ * @function loadPrimaryUserSecrets
+ * @returns {Object} Loaded secrets object or empty object
+ */
+function loadPrimaryUserSecrets() {
+  const primaryDir = pathsUtil.getConfigDirForPaths();
+  const userSecretsPath = path.join(primaryDir, 'secrets.local.yaml');
+  if (!fs.existsSync(userSecretsPath)) {
+    return {};
+  }
+
+  try {
+    const content = fs.readFileSync(userSecretsPath, 'utf8');
+    const secrets = parseSecretsContent(content);
+    if (!secrets || typeof secrets !== 'object') {
+      throw new Error(`Invalid secrets file format: ${userSecretsPath}`);
+    }
+    return secrets;
+  } catch (error) {
+    if (error.message.includes('Invalid secrets file format')) {
+      throw error;
+    }
+    logger.warn(`Warning: Could not read secrets file ${userSecretsPath}: ${error.message}`);
+    return {};
+  }
+}
+
 /**
  * Loads user secrets from ~/.aifabrix/secrets.local.yaml
  * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override
@@ -59,7 +109,7 @@ function loadUserSecrets() {
 
   try {
     const content = fs.readFileSync(userSecretsPath, 'utf8');
-    const secrets = yaml.load(content);
+    const secrets = parseSecretsContent(content);
     if (!secrets || typeof secrets !== 'object') {
       throw new Error(`Invalid secrets file format: ${userSecretsPath}`);
     }
@@ -157,6 +207,7 @@ function resolveUrlPort(protocol, hostname, port, urlPath, hostnameToService) {
 
 module.exports = {
   loadSecretsFromFile,
+  loadPrimaryUserSecrets,
   loadUserSecrets,
   loadDefaultSecrets,
   buildHostnameToServiceMap,

package/lib/utils/secrets-validation.js

@@ -0,0 +1,84 @@
+/**
+ * AI Fabrix Builder – Secrets file validation
+ *
+ * Validates secrets.local.yaml (or given path): valid YAML, flat key-value structure,
+ * and optional naming convention (*KeyVault suffix per keyvault.md).
+ *
+ * @fileoverview Secrets file validation for structure and naming
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Optional naming convention: keys should end with KeyVault or match known patterns.
+ * @param {string} key - Secret key
+ * @returns {boolean} True if key matches convention
+ */
+function keyMatchesNamingConvention(key) {
+  if (!key || typeof key !== 'string') return false;
+  if (key.endsWith('KeyVault')) return true;
+  return /^[a-z0-9-_]+KeyVault$/i.test(key);
+}
+
+/**
+ * Validate that parsed secrets is a flat object (no nested objects for values).
+ * @param {*} parsed - Parsed YAML
+ * @param {boolean} checkNaming - Whether to check key naming
+ * @returns {string[]} Errors
+ */
+function validateParsedSecrets(parsed, checkNaming) {
+  const errors = [];
+  if (parsed === null || parsed === undefined) return errors;
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    errors.push('Secrets file must be a flat key-value object (no nested objects or arrays)');
+    return errors;
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value !== 'string' && typeof value !== 'number' && value !== null && value !== undefined) {
+      if (typeof value === 'object') {
+        errors.push(`Key "${key}": secret values must be strings or scalars (no nested objects)`);
+      }
+    }
+    if (checkNaming && !keyMatchesNamingConvention(key)) {
+      errors.push(`Key "${key}": recommended format is *KeyVault (e.g. postgres-passwordKeyVault)`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * Validate secrets file at path: YAML syntax, flat object, optional naming check.
+ *
+ * @param {string} filePath - Path to secrets file
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.checkNaming=false] - Check key names against *KeyVault convention
+ * @returns {{ valid: boolean, errors: string[], path: string }}
+ */
+function validateSecretsFile(filePath, options = {}) {
+  const checkNaming = Boolean(options.checkNaming);
+  if (!filePath || typeof filePath !== 'string') {
+    return { valid: false, errors: ['Path is required'], path: '' };
+  }
+  const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  if (!fs.existsSync(resolvedPath)) {
+    return { valid: false, errors: [`File not found: ${resolvedPath}`], path: resolvedPath };
+  }
+  let parsed;
+  try {
+    const content = fs.readFileSync(resolvedPath, 'utf8');
+    parsed = yaml.load(content);
+  } catch (err) {
+    return { valid: false, errors: [`Invalid YAML: ${err.message}`], path: resolvedPath };
+  }
+  const errors = validateParsedSecrets(parsed, checkNaming);
+  return { valid: errors.length === 0, errors, path: resolvedPath };
+}
+
+module.exports = {
+  validateSecretsFile,
+  keyMatchesNamingConvention
+};

package/lib/utils/ssh-key-helper.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Locate or generate SSH key for Mutagen sync (Windows and Mac). Prefer ed25519.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+/**
+ * Default SSH directory (user's .ssh)
+ * @returns {string} Path to .ssh directory
+ */
+function getDefaultSshDir() {
+  const home = os.homedir();
+  return path.join(home, '.ssh');
+}
+
+/**
+ * Path to default ed25519 public key
+ * @returns {string} Path to id_ed25519.pub
+ */
+function getDefaultEd25519PublicKeyPath() {
+  return path.join(getDefaultSshDir(), 'id_ed25519.pub');
+}
+
+/**
+ * Path to default ed25519 private key
+ * @returns {string} Path to id_ed25519
+ */
+function getDefaultEd25519PrivateKeyPath() {
+  return path.join(getDefaultSshDir(), 'id_ed25519');
+}
+
+/**
+ * Ensure .ssh directory exists
+ * @param {string} [sshDir] - SSH directory (default: user .ssh)
+ * @returns {string} Resolved SSH dir path
+ */
+function ensureSshDir(sshDir) {
+  const dir = sshDir || getDefaultSshDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  return dir;
+}
+
+/**
+ * Generate ed25519 SSH key pair if it does not exist. Idempotent.
+ * @param {string} [privateKeyPath] - Path to private key (default: ~/.ssh/id_ed25519)
+ * @returns {string} Path to public key file
+ * @throws {Error} If ssh-keygen fails
+ */
+function ensureEd25519Key(privateKeyPath) {
+  const privPath = privateKeyPath || getDefaultEd25519PrivateKeyPath();
+  const pubPath = privPath + '.pub';
+  if (fs.existsSync(pubPath) && fs.existsSync(privPath)) {
+    return pubPath;
+  }
+  ensureSshDir(path.dirname(privPath));
+  execSync(`ssh-keygen -t ed25519 -f "${privPath}" -N "" -C "aifabrix"`, {
+    stdio: 'pipe',
+    encoding: 'utf8'
+  });
+  return pubPath;
+}
+
+/**
+ * Read public key content (single line). Prefer ed25519, fallback to id_rsa.pub.
+ * @param {string} [sshDir] - SSH directory
+ * @returns {string} Public key line (e.g. "ssh-ed25519 AAAA... aifabrix")
+ * @throws {Error} If no key found or read fails
+ */
+function readPublicKeyContent(sshDir) {
+  const dir = sshDir || getDefaultSshDir();
+  const ed25519Pub = path.join(dir, 'id_ed25519.pub');
+  const rsaPub = path.join(dir, 'id_rsa.pub');
+  let pathToRead = null;
+  if (fs.existsSync(ed25519Pub)) {
+    pathToRead = ed25519Pub;
+  } else if (fs.existsSync(rsaPub)) {
+    pathToRead = rsaPub;
+  }
+  if (!pathToRead) {
+    throw new Error(
+      'No SSH public key found. Run: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "aifabrix"'
+    );
+  }
+  const content = fs.readFileSync(pathToRead, 'utf8').trim();
+  const firstLine = content.split('\n')[0];
+  if (!firstLine || !firstLine.startsWith('ssh-')) {
+    throw new Error(`Invalid SSH public key file: ${pathToRead}`);
+  }
+  return firstLine;
+}
+
+/**
+ * Get or create ed25519 key and return its public key content for POST /api/dev/users/:id/ssh-keys.
+ * @returns {string} Single-line public key content
+ */
+function getOrCreatePublicKeyContent() {
+  ensureEd25519Key();
+  return readPublicKeyContent();
+}
+
+module.exports = {
+  getDefaultSshDir,
+  getDefaultEd25519PublicKeyPath,
+  getDefaultEd25519PrivateKeyPath,
+  ensureSshDir,
+  ensureEd25519Key,
+  readPublicKeyContent,
+  getOrCreatePublicKeyContent
+};

package/lib/utils/test-log-writer.js

@@ -0,0 +1,56 @@
+/**
+ * Test log writer - writes debug logs to integration/<appKey>/logs/
+ * Sanitization (tokens, secrets) is done by dataplane before responses are returned.
+ *
+ * @fileoverview Write test request/response logs for debugging
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Prepare object for JSON serialization (handles circular refs)
+ * @param {*} obj - Object to prepare
+ * @param {Set} [seen] - Set of seen object references (for circular refs)
+ * @returns {*} Copy safe for JSON.stringify
+ */
+function sanitizeForLog(obj, seen = new Set()) {
+  if (obj === null || obj === undefined || typeof obj !== 'object') return obj;
+  if (seen.has(obj)) return '[Circular]';
+  seen.add(obj);
+  if (Array.isArray(obj)) return obj.map(item => sanitizeForLog(item, seen));
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    out[key] = sanitizeForLog(value, seen);
+  }
+  return out;
+}
+
+/**
+ * Write test log to integration/<appKey>/logs/<logType>-<timestamp>.json
+ * @async
+ * @param {string} appKey - Application key (used for path)
+ * @param {Object} data - Log data (request, response) - will be sanitized
+ * @param {string} [logType] - Log type prefix (default: test-integration)
+ * @param {string} [integrationBaseDir] - Base dir for integration (default: cwd/integration)
+ * @returns {Promise<string>} Path to written file
+ * @throws {Error} If write fails
+ */
+async function writeTestLog(appKey, data, logType = 'test-integration', integrationBaseDir) {
+  const baseDir = integrationBaseDir || path.join(process.cwd(), 'integration');
+  const logsDir = path.join(baseDir, appKey, 'logs');
+  await fs.mkdir(logsDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const filename = `${logType}-${timestamp}.json`;
+  const filePath = path.join(logsDir, filename);
+  const sanitized = sanitizeForLog(data);
+  await fs.writeFile(filePath, JSON.stringify(sanitized, null, 2), 'utf8');
+  return filePath;
+}
+
+module.exports = {
+  sanitizeForLog,
+  writeTestLog
+};