@aifabrix/builder 2.44.5 → 2.44.6

package/lib/utils/paths.js

@@ -17,6 +17,7 @@ const {
   getAifabrixRuntimeConfigDir,
   resolveAifabrixHomeLikePath
 } = require('./aifabrix-runtime-config-dir');
+const { resolveSystemBuilderParentDir } = require('./system-builder-root');
 
 function safeHomedir() {
   try {
@@ -43,14 +44,13 @@ function getConfigDirForPaths() {
 }
 
 /**
- * User-owned `secrets.local.yaml` beside effective `config.yaml` (see {@link getConfigDirForPaths}).
- * When `AIFABRIX_HOME` is `$HOME` but config is only at `$HOME/.aifabrix/config.yaml`, uses that folder.
- * Keeps `secret list` / `secret set` aligned with resolve merge (`loadPrimaryUserSecrets`).
+ * User-owned `secrets.local.yaml` under {@link getAifabrixHome} (same rule as `aifabrix-home` in
+ * `config.yaml`, else `~/.aifabrix`). Keeps `secret set` / merge loaders aligned with declared home.
  *
  * @returns {string} Absolute path to secrets.local.yaml
  */
 function getPrimaryUserSecretsLocalPath() {
-  return path.join(getConfigDirForPaths(), 'secrets.local.yaml');
+  return path.join(getAifabrixHome(), 'secrets.local.yaml');
 }
 
 /**
@@ -327,7 +327,7 @@ function getAppPath(appName, appType) {
   if (appType === 'external') {
     return getIntegrationPath(appName);
   }
-  return path.join(getBuilderRoot(), appName);
+  return getBuilderPath(appName);
 }
 
 /**
@@ -342,7 +342,7 @@ function getIntegrationBuilderBaseDir() {
     const workNorm = path.resolve(work);
     const integrationUnderWork = path.join(workNorm, 'integration');
     try {
-      if (fs.existsSync(integrationUnderWork)) {
+      if (nodeFs().existsSync(integrationUnderWork)) {
         return workNorm;
       }
     } catch {
@@ -380,6 +380,60 @@ function getBuilderRoot() {
   return path.join(getIntegrationBuilderBaseDir(), 'builder');
 }
 
+/**
+ * Platform system apps: project `builder/<app>` when present; else `builder/<app>` under the
+ * resolved system-builder parent (config dir, or `aifabrix-home` when outside config — see
+ * {@link getSystemBuilderRoot}).
+ * @readonly
+ */
+const SYSTEM_BUILDER_APP_KEYS = Object.freeze(['keycloak', 'miso-controller', 'dataplane']);
+
+/**
+ * @param {string} appName
+ * @returns {boolean}
+ */
+function isSystemBuilderAppName(appName) {
+  if (!appName || typeof appName !== 'string') return false;
+  return SYSTEM_BUILDER_APP_KEYS.includes(appName);
+}
+
+/**
+ * Project/cwd `builder/<appName>` (no existence check).
+ * @param {string} appName
+ * @returns {string}
+ */
+function getProjectBuilderAppPath(appName) {
+  return path.join(getIntegrationBuilderBaseDir(), 'builder', appName);
+}
+
+/**
+ * Directory containing default materialization for platform apps: `<parent>/builder/<app>`.
+ * Parent is {@link getAifabrixSystemDir} when that path lies under {@link getAifabrixHome};
+ * otherwise {@link getAifabrixHome} (honours `aifabrix-home` / `AIFABRIX_HOME` vs config location).
+ *
+ * @returns {string}
+ */
+function getSystemBuilderRoot() {
+  return path.join(
+    resolveSystemBuilderParentDir(getAifabrixSystemDir(), getAifabrixHome()),
+    'builder'
+  );
+}
+
+/**
+ * @param {string} projectAppPath - Absolute `.../builder/<app>`
+ * @returns {boolean}
+ */
+function isProjectBuilderAppDirectory(projectAppPath) {
+  try {
+    if (!projectAppPath || !nodeFs().existsSync(projectAppPath)) return false;
+    const st = nodeFs().statSync(projectAppPath);
+    return Boolean(st && typeof st.isDirectory === 'function' && st.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
 /**
  * True when name under root is a real directory (follows symlinks). False for broken symlinks, files, ENOENT.
  * @param {string} root - Parent directory (must exist)
@@ -422,27 +476,44 @@ function listIntegrationAppNames() {
 }
 
 /**
- * Lists app names (directories) under builder root. Excludes dot-prefixed entries.
- * Returns [] if root does not exist.
- * @returns {string[]} Sorted list of app directory names
+ * Adds immediate subdirectory names under a builder root into `names` (real disk via {@link nodeFs}).
+ * @param {ReturnType<typeof nodeFs>} disk
+ * @param {string} builderRootDir
+ * @param {Set<string>} names
+ * @param {(name: string) => boolean} [nameFilter] - When set, only names passing this filter (after dir check)
  */
-function listBuilderAppNames() {
-  const disk = nodeFs();
-  const root = getBuilderRoot();
-  if (!disk.existsSync(root)) {
-    return [];
-  }
-  let rootStat;
+function addBuilderSubdirNamesToSet(disk, builderRootDir, names, nameFilter) {
+  if (!builderRootDir || !disk.existsSync(builderRootDir)) return;
+  let st;
   try {
-    rootStat = disk.statSync(root);
+    st = disk.statSync(builderRootDir);
   } catch {
-    return [];
+    return;
   }
-  if (!rootStat || typeof rootStat.isDirectory !== 'function' || !rootStat.isDirectory()) {
-    return [];
+  if (!st || typeof st.isDirectory !== 'function' || !st.isDirectory()) return;
+  try {
+    for (const name of disk.readdirSync(builderRootDir)) {
+      if (!isAppSubdirSync(builderRootDir, name)) continue;
+      if (nameFilter && !nameFilter(name)) continue;
+      names.add(name);
+    }
+  } catch {
+    // ignore
   }
-  const entries = disk.readdirSync(root);
-  return entries.filter((name) => isAppSubdirSync(root, name)).sort();
+}
+
+/**
+ * Lists app names (directories) under builder root. Excludes dot-prefixed entries.
+ * Merges project `builder/` with system builder root (platform keys only under the latter).
+ * @returns {string[]} Sorted list of app directory names
+ */
+function listBuilderAppNames() {
+  const disk = nodeFs();
+  const names = new Set();
+  const projectBuilder = path.join(getIntegrationBuilderBaseDir(), 'builder');
+  addBuilderSubdirNamesToSet(disk, projectBuilder, names, null);
+  addBuilderSubdirNamesToSet(disk, getSystemBuilderRoot(), names, isSystemBuilderAppName);
+  return [...names].sort();
 }
 
 /**
@@ -481,11 +552,18 @@ function getBuilderPath(appName) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-  const builderRoot = process.env.AIFABRIX_BUILDER_DIR && typeof process.env.AIFABRIX_BUILDER_DIR === 'string'
+  const envBuilderRoot = process.env.AIFABRIX_BUILDER_DIR && typeof process.env.AIFABRIX_BUILDER_DIR === 'string'
     ? process.env.AIFABRIX_BUILDER_DIR.trim()
     : null;
-  if (builderRoot) {
-    return path.join(path.resolve(builderRoot), appName);
+  if (envBuilderRoot) {
+    return path.join(path.resolve(envBuilderRoot), appName);
+  }
+  if (isSystemBuilderAppName(appName)) {
+    const projectAppPath = getProjectBuilderAppPath(appName);
+    if (isProjectBuilderAppDirectory(projectAppPath)) {
+      return projectAppPath;
+    }
+    return path.join(getSystemBuilderRoot(), appName);
   }
   const base = getIntegrationBuilderBaseDir();
   return path.join(base, 'builder', appName);
@@ -665,6 +743,11 @@ module.exports = {
   getBuilderPath,
   getIntegrationRoot,
   getBuilderRoot,
+  SYSTEM_BUILDER_APP_KEYS,
+  isSystemBuilderAppName,
+  getProjectBuilderAppPath,
+  getSystemBuilderRoot,
+  resolveSystemBuilderParentDir,
   listIntegrationAppNames,
   listBuilderAppNames,
   resolveBuildContext,

package/lib/utils/postgres-wipe.js

@@ -0,0 +1,212 @@
+/**
+ * Postgres data wipe helper for `aifabrix setup` Mode 2 (Wipe data).
+ *
+ * Drops every non-template database and every non-superuser role in the
+ * developer's running Postgres container, while preserving the volume,
+ * the `postgres` superuser, and the admin password (so the post-wipe
+ * `up-infra` and platform bootstrap recreate schemas + service users).
+ *
+ * Uses `docker exec` with the admin password passed via the container's
+ * environment (PGPASSWORD) so it is not visible in `ps`.
+ *
+ * @fileoverview Drop all DBs and roles in dev Postgres for setup Mode 2
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+const adminSecrets = require('../core/admin-secrets');
+const dockerExec = require('./docker-exec');
+const logger = require('./logger');
+const chalk = require('chalk');
+const { successGlyph } = require('./cli-test-layout-chalk');
+
+/** Roles that must never be dropped (Postgres-managed predefined roles). */
+const PROTECTED_ROLES = new Set([
+  // In this project, infra starts Postgres with POSTGRES_USER=pgadmin (see templates/infra/compose.yaml.hbs),
+  // so that role is the superuser we must preserve.
+  'pgadmin',
+  // Legacy / default superuser name for official Postgres images.
+  'postgres',
+  'pg_signal_backend',
+  'pg_read_server_files',
+  'pg_write_server_files',
+  'pg_execute_server_program',
+  'pg_monitor',
+  'pg_read_all_settings',
+  'pg_read_all_stats',
+  'pg_stat_scan_tables',
+  'pg_database_owner',
+  'pg_read_all_data',
+  'pg_write_all_data',
+  'pg_checkpoint',
+  'pg_use_reserved_connections',
+  'pg_create_subscription'
+]);
+
+/** Databases that must never be dropped. */
+const PROTECTED_DATABASES = new Set(['postgres', 'template0', 'template1']);
+
+/** Superuser role used inside the infra Postgres container. */
+const SUPERUSER_ROLE = 'pgadmin';
+
+/**
+ * Compute the developer-scoped Postgres container name.
+ * Mirrors `getInfraContainerNames` in `lib/utils/infra-status.js`.
+ * @param {number|string} devId - Developer ID
+ * @returns {string}
+ */
+function getPostgresContainerName(devId) {
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  if (idNum === 0) return 'aifabrix-postgres';
+  return `aifabrix-dev${devId}-postgres`;
+}
+
+/**
+ * Run `psql -t -A -c <sql>` inside the Postgres container with PGPASSWORD set
+ * via `-e PGPASSWORD=...` so the secret never appears on the command line.
+ *
+ * @async
+ * @param {string} container - Container name
+ * @param {string} sql - Single SQL statement (no shell metacharacters)
+ * @param {string} adminPassword - Postgres superuser password
+ * @returns {Promise<string>} stdout (trimmed)
+ * @throws {Error} If the docker exec invocation fails
+ */
+async function runPsql(container, sql, adminPassword) {
+  if (!container || typeof container !== 'string') {
+    throw new Error('Postgres container name is required');
+  }
+  if (!sql || typeof sql !== 'string') {
+    throw new Error('SQL statement is required');
+  }
+  if (!adminPassword || typeof adminPassword !== 'string') {
+    throw new Error('Admin password is required');
+  }
+  const escapedSql = sql.replace(/"/g, '\\"');
+  const cmd = `docker exec -e PGPASSWORD -i ${container} psql -U ${SUPERUSER_ROLE} -d postgres -tAc "${escapedSql}"`;
+  const env = { PGPASSWORD: adminPassword };
+  const result = (await dockerExec.execWithDockerEnv(cmd, { env })) || {};
+  return String(result.stdout || '').trim();
+}
+
+/**
+ * List user databases (non-template, not in PROTECTED_DATABASES).
+ * @async
+ * @param {string} container - Container name
+ * @param {string} adminPassword - Postgres superuser password
+ * @returns {Promise<string[]>} database names
+ */
+async function listUserDatabases(container, adminPassword) {
+  const out = await runPsql(
+    container,
+    'SELECT datname FROM pg_database WHERE datistemplate = false;',
+    adminPassword
+  );
+  return out
+    .split('\n')
+    .map(s => s.trim())
+    .filter(name => name && !PROTECTED_DATABASES.has(name));
+}
+
+/**
+ * List dropable roles (non-superuser, not in PROTECTED_ROLES).
+ * @async
+ * @param {string} container - Container name
+ * @param {string} adminPassword - Postgres superuser password
+ * @returns {Promise<string[]>} role names
+ */
+async function listDropableRoles(container, adminPassword) {
+  const out = await runPsql(
+    container,
+    'SELECT rolname FROM pg_roles WHERE rolsuper = false;',
+    adminPassword
+  );
+  return out
+    .split('\n')
+    .map(s => s.trim())
+    .filter(name => name && !PROTECTED_ROLES.has(name) && !name.startsWith('pg_'));
+}
+
+/**
+ * Drop a single database (forces disconnection of active sessions).
+ * @async
+ * @param {string} container
+ * @param {string} dbName
+ * @param {string} adminPassword
+ * @returns {Promise<void>}
+ */
+async function dropDatabase(container, dbName, adminPassword) {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(dbName)) {
+    throw new Error(`Refusing to drop database with unsafe name: ${dbName}`);
+  }
+  await runPsql(
+    container,
+    `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${dbName}' AND pid <> pg_backend_pid();`,
+    adminPassword
+  );
+  await runPsql(container, `DROP DATABASE IF EXISTS "${dbName}";`, adminPassword);
+}
+
+/**
+ * Drop a single role (REASSIGN OWNED + DROP OWNED first to clear dependencies).
+ * @async
+ * @param {string} container
+ * @param {string} role
+ * @param {string} adminPassword
+ * @returns {Promise<void>}
+ */
+async function dropRole(container, role, adminPassword) {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(role)) {
+    throw new Error(`Refusing to drop role with unsafe name: ${role}`);
+  }
+  await runPsql(
+    container,
+    `REASSIGN OWNED BY "${role}" TO ${SUPERUSER_ROLE};`,
+    adminPassword
+  ).catch(() => undefined);
+  await runPsql(container, `DROP OWNED BY "${role}" CASCADE;`, adminPassword).catch(() => undefined);
+  await runPsql(container, `DROP ROLE IF EXISTS "${role}";`, adminPassword);
+}
+
+/**
+ * Drop every non-template database and every non-superuser role in the
+ * developer's running Postgres container. Caller must ensure infra is up.
+ *
+ * @async
+ * @function wipePostgresData
+ * @returns {Promise<{ databases: string[], roles: string[] }>} dropped names
+ * @throws {Error} If admin secrets are missing or psql calls fail
+ */
+async function wipePostgresData() {
+  const devId = await config.getDeveloperId();
+  const container = getPostgresContainerName(devId);
+  const admin = await adminSecrets.readAndDecryptAdminSecrets();
+  const password = admin && admin.POSTGRES_PASSWORD;
+  if (!password) {
+    throw new Error('POSTGRES_PASSWORD not found in admin-secrets.env. Run "aifabrix up-infra" first.');
+  }
+
+  const databases = await listUserDatabases(container, password);
+  for (const dbName of databases) {
+    await dropDatabase(container, dbName, password);
+    logger.log(chalk.gray(` ${successGlyph()} Dropped database ${dbName}`));
+  }
+
+  const roles = await listDropableRoles(container, password);
+  for (const role of roles) {
+    await dropRole(container, role, password);
+    logger.log(chalk.gray(` ${successGlyph()} Dropped role ${role}`));
+  }
+
+  return { databases, roles };
+}
+
+module.exports = {
+  wipePostgresData,
+  getPostgresContainerName,
+  PROTECTED_DATABASES,
+  PROTECTED_ROLES
+};

package/lib/utils/register-aifabrix-shell-env.js

@@ -191,8 +191,23 @@ async function registerAifabrixShellEnvFromConfig(getConfigFn, overrides = {}) {
   await applyPosixShellEnv(homeAbs, workAbs, overrides);
 }
 
+/**
+ * Build sh export lines for AIFABRIX_HOME / AIFABRIX_WORK from current config (stdout for eval).
+ *
+ * @async
+ * @param {function(): Promise<object>} getConfigFn - Same as config.getConfig
+ * @returns {Promise<string>} Lines suitable for `eval "$(aifabrix dev shell-env)"` on bash/zsh
+ */
+async function buildShellEnvExportsFromConfig(getConfigFn) {
+  const config = await getConfigFn();
+  const homeAbs = absFromConfigRaw(config['aifabrix-home']);
+  const workAbs = absFromConfigRaw(config['aifabrix-work']);
+  return buildPosixShellEnvBody(homeAbs, workAbs);
+}
+
 module.exports = {
   registerAifabrixShellEnvFromConfig,
+  buildShellEnvExportsFromConfig,
   buildPosixShellEnvBody,
   buildProfileBlock,
   shSingleQuoted,

package/lib/utils/remote-dev-auth.js

@@ -5,10 +5,25 @@
  */
 
 const path = require('path');
+const os = require('os');
 const config = require('../core/config');
 const { getCertDir, readClientCertPem, readServerCaPem } = require('./dev-cert-helper');
 const { getConfigDirForPaths, getAifabrixHome, getAifabrixWork } = require('./paths');
 
+/**
+ * Same rules as {@link module:lib/core/config.expandTilde} / {@link module:lib/core/config.getSecretsPath}.
+ * Inline here so `resolveSharedSecretsEndpoint` stays aligned with `getSecretsPath()` even when `getAifabrixSecretsPath()`
+ * returns the raw config string (tilde not expanded).
+ */
+function expandConfiguredSecretsTilde(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;
+}
+
 /**
  * Single API object so resolveSharedSecretsEndpoint and callers share one getRemoteDevAuth
  * (Jest spies and partial mocks work reliably).
@@ -54,16 +69,17 @@ const remoteDevAuth = {
     const trimmed = configuredPath.trim();
     if (!trimmed) return configuredPath;
     if (remoteDevAuth.isRemoteSecretsUrl(trimmed)) return trimmed.replace(/\/+$/, '');
+    const expanded = expandConfiguredSecretsTilde(trimmed);
     const auth = await remoteDevAuth.getRemoteDevAuth();
-    if (!auth) return configuredPath;
-    const abs = normalizeSharedSecretsFilePath(trimmed);
-    if (!abs) return configuredPath;
+    if (!auth) return expanded;
+    const abs = normalizeSharedSecretsFilePath(expanded);
+    if (!abs) return expanded;
     const home = path.normalize(getAifabrixHome());
-    if (isPathUnderDir(abs, home)) return configuredPath;
+    if (isPathUnderDir(abs, home)) return expanded;
     const work = getAifabrixWork();
     if (work) {
       const w = path.normalize(work);
-      if (isPathUnderDir(abs, w)) return configuredPath;
+      if (isPathUnderDir(abs, w)) return expanded;
     }
     const base = String(auth.serverUrl).replace(/\/+$/, '');
     return `${base}/api/dev/secrets`;

package/lib/utils/remote-docker-env.js

@@ -89,7 +89,15 @@ async function getDockerExecEnv() {
   if (overlay.DOCKER_HOST && !Object.prototype.hasOwnProperty.call(overlay, 'DOCKER_CERT_PATH')) {
     delete merged.DOCKER_CERT_PATH;
   }
-  return { ...merged, ...overlay };
+  let out = { ...merged, ...overlay };
+  try {
+    const { getBashPrefixedProcessEnvOverlay } = require('./bash-secret-env');
+    const bash = await getBashPrefixedProcessEnvOverlay();
+    out = { ...out, ...bash };
+  } catch {
+    /* ignore secrets load failures; Docker CLI still runs with process + remote env */
+  }
+  return out;
 }
 
 module.exports = { getRemoteDockerEnv, getDockerExecEnv };

package/lib/utils/remote-secrets-loader.js

@@ -1,13 +1,17 @@
 /**
- * Load shared secrets from Builder Server when aifabrix-secrets is an http(s) URL.
- * Used for .env resolution only; values are never persisted to disk.
+ * Load shared secrets from Builder Server when aifabrix-secrets is an http(s) URL,
+ * or from the configured shared YAML path when it targets a local file.
  *
  * @fileoverview Remote shared secrets loader for .env generation
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
+const fs = require('fs');
+const path = require('path');
 const config = require('../core/config');
+const { readYamlAtPath } = require('./secrets-canonical');
+const { ensureSecureFilePermissions } = require('./secure-file-permissions');
 
 /**
  * Fetches shared secrets from Builder Server when aifabrix-secrets is an http(s) URL.
@@ -63,7 +67,42 @@ function mergeUserWithRemoteSecrets(userSecrets, remoteSecrets) {
   return merged;
 }
 
+/**
+ * Raw secrets from the configured shared store only (`aifabrix-secrets`): remote Builder API or shared YAML file.
+ * Does not include primary user secrets or builder merges. Used to avoid duplicating shared keys into ~/.aifabrix.
+ *
+ * @returns {Promise<Object|null>} Key-value map or null when unavailable / not configured
+ */
+async function loadConfiguredSharedSecretsStore() {
+  const remoteDevAuth = require('./remote-dev-auth');
+  const configSecretsPath = await config.getSecretsPath();
+  if (!configSecretsPath) {
+    return null;
+  }
+  const endpoint = await remoteDevAuth.resolveSharedSecretsEndpoint(configSecretsPath);
+  if (remoteDevAuth.isRemoteSecretsUrl(endpoint)) {
+    return loadRemoteSharedSecrets();
+  }
+  const resolvedFile = path.isAbsolute(endpoint)
+    ? endpoint
+    : path.resolve(process.cwd(), endpoint);
+  if (!fs.existsSync(resolvedFile)) {
+    return null;
+  }
+  try {
+    ensureSecureFilePermissions(resolvedFile);
+    const data = readYamlAtPath(resolvedFile);
+    if (!data || typeof data !== 'object') {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
 module.exports = {
   loadRemoteSharedSecrets,
-  mergeUserWithRemoteSecrets
+  mergeUserWithRemoteSecrets,
+  loadConfiguredSharedSecretsStore
 };

package/lib/utils/resolve-docker-image-ref.js

@@ -73,16 +73,21 @@ function normalizeDockerRegistryPrefix(registry) {
  */
 function resolveDockerImageRef(appName, appConfig, runOptions = {}) {
   const opts = runOptions || {};
+  const tagFromOpts =
+    opts.tag !== undefined && opts.tag !== null && String(opts.tag).trim() !== ''
+      ? String(opts.tag).trim()
+      : null;
+
   if (opts.image) {
     const parsed = parseImageOverride(opts.image);
     return {
       imageName: parsed ? parsed.name : getRepositoryPathFromConfig(appConfig, appName),
-      imageTag: parsed ? parsed.tag : imageTagFromConfig(appConfig)
+      imageTag: parsed ? parsed.tag : tagFromOpts || imageTagFromConfig(appConfig)
     };
   }
 
   const baseRepo = getRepositoryPathFromConfig(appConfig, appName);
-  const imageTag = imageTagFromConfig(appConfig);
+  const imageTag = tagFromOpts || imageTagFromConfig(appConfig);
   const prefix =
     normalizeDockerRegistryPrefix(opts.registry) ||
     normalizeDockerRegistryPrefix(appConfig?.image?.registry ?? '');
@@ -120,5 +125,6 @@ module.exports = {
   resolveDockerImageRef,
   resolveComposeImageOverrideString,
   normalizeDockerRegistryPrefix,
-  getRepositoryPathFromConfig
+  getRepositoryPathFromConfig,
+  imageTagFromConfig
 };

package/lib/utils/secrets-ancestor-paths.js

@@ -0,0 +1,47 @@
+/**
+ * Collect `secrets.local.yaml` paths along the cwd → root walk so parent workspace
+ * secrets (e.g. `/workspace/.aifabrix/`) merge when the active config is nested
+ * (e.g. `repo/.aifabrix/` from cwd).
+ *
+ * @fileoverview Ancestor secrets.local.yaml discovery for loadSecrets cascade
+ */
+
+'use strict';
+
+const path = require('path');
+
+const MAX_ANCESTOR_STEPS = 64;
+
+/**
+ * @param {string} startDir - Directory to start from (typically process.cwd())
+ * @param {(p: string) => boolean} existsSyncFn - Sync existence check
+ * @returns {string[]} Absolute paths, nearest ancestor first (cwd-side), then parents
+ */
+function collectAncestorAifabrixSecretsLocalYamlPaths(startDir, existsSyncFn) {
+  if (!startDir || typeof startDir !== 'string' || typeof existsSyncFn !== 'function') {
+    return [];
+  }
+  const out = [];
+  const seen = new Set();
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < MAX_ANCESTOR_STEPS; i += 1) {
+    const secretsPath = path.join(dir, '.aifabrix', 'secrets.local.yaml');
+    if (existsSyncFn(secretsPath)) {
+      const abs = path.resolve(secretsPath);
+      if (!seen.has(abs)) {
+        seen.add(abs);
+        out.push(abs);
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return out;
+}
+
+module.exports = {
+  collectAncestorAifabrixSecretsLocalYamlPaths
+};