@aifabrix/builder 2.42.1 → 2.44.0

package/lib/utils/port-resolver.js

@@ -3,7 +3,7 @@
  *
  * Single source of truth for resolving application port from application config.
  * Use getContainerPort for container/Docker/deployment/registration; use getLocalPort
- * for local .env and dev-id–adjusted host port.
+ * for manifest listen port (same as port; local host uses port+10+dev*100 in secrets-helpers).
  *
  * @fileoverview Port resolution from variables (port, build.containerPort)
  * @author AI Fabrix Team
@@ -14,6 +14,7 @@
 
 const fs = require('fs');
 const yaml = require('js-yaml');
+const { DECLARATIVE_URL_INFRA_DEFAULTS } = require('./infra-env-defaults');
 
 /**
  * Resolve container port from variables object.
@@ -21,10 +22,10 @@ const yaml = require('js-yaml');
  * When containerPort is empty or missing, main port is used (e.g. keycloak 8082:8080 vs miso 3000:3000).
  *
  * @param {Object} variables - Parsed application config (or subset with build, port)
- * @param {number} [defaultPort=3000] - Default when neither build.containerPort nor port is set
+ * @param {number} [defaultPort] - Default when neither build.containerPort nor port is set (infra fallback)
  * @returns {number} Resolved container port
  */
-function getContainerPort(variables, defaultPort = 3000) {
+function getContainerPort(variables, defaultPort = DECLARATIVE_URL_INFRA_DEFAULTS.manifestPortFallback) {
   const v = variables || {};
   const containerPort = v.build?.containerPort;
   const useMain = containerPort === undefined || containerPort === null ||
@@ -36,20 +37,13 @@ function getContainerPort(variables, defaultPort = 3000) {
 }
 
 /**
- * Resolve local (development) port from variables object.
- * Precedence: build.localPort (when positive integer) → port → defaultPort.
- * Used for env-copy, env-ports, getLocalPortFromPath, run compose host port.
- *
+ * Resolve base application listen port (manifest `port` only; build.localPort removed).
  * @param {Object} variables - Parsed application config
- * @param {number} [defaultPort=3000] - Default when neither build.localPort nor port is set
- * @returns {number} Resolved local port
+ * @param {number} [defaultPort] - Default when port is unset (infra fallback)
+ * @returns {number} Listen port
  */
-function getLocalPort(variables, defaultPort = 3000) {
+function getLocalPort(variables, defaultPort = DECLARATIVE_URL_INFRA_DEFAULTS.manifestPortFallback) {
   const v = variables || {};
-  const localPort = v.build?.localPort;
-  if (typeof localPort === 'number' && localPort > 0) {
-    return localPort;
-  }
   return v.port ?? defaultPort;
 }
 
@@ -94,22 +88,15 @@ function getContainerPortFromPath(variablesPath) {
 }
 
 /**
- * Resolve local port from application config path.
- * Same rule as getLocalPort: build.localPort (when positive integer) → port.
- * Returns null when file is missing or neither localPort nor port is set.
- *
+ * Resolve manifest port from application config path.
  * @param {string} variablesPath - Path to application config
- * @returns {number|null} Local port or null
+ * @returns {number|null} Port or null
  */
 function getLocalPortFromPath(variablesPath) {
   const v = loadVariablesFromPath(variablesPath);
   if (!v) {
     return null;
   }
-  const localPort = v.build?.localPort;
-  if (typeof localPort === 'number' && localPort > 0) {
-    return localPort;
-  }
   const p = v.port;
   return (p !== undefined && p !== null) ? p : null;
 }

package/lib/utils/redis-env-scope.js

@@ -0,0 +1,62 @@
+/**
+ * Adjust Redis DB index in resolved .env content when environment-scoped resources are effective.
+ *
+ * @fileoverview REDIS_DB and redis:// URL path segment (plan 117)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Set pathname /dbIndex for redis(s) URLs.
+ *
+ * @param {string} urlStr - redis:// or rediss:// URL
+ * @param {number} dbIndex - logical DB (0–15 typical)
+ * @returns {string}
+ */
+function setRedisUrlDbIndex(urlStr, dbIndex) {
+  if (!urlStr || typeof urlStr !== 'string') return urlStr;
+  try {
+    const u = new URL(urlStr.trim());
+    if (u.protocol !== 'redis:' && u.protocol !== 'rediss:') {
+      return urlStr;
+    }
+    u.pathname = `/${dbIndex}`;
+    return u.toString();
+  } catch {
+    return urlStr;
+  }
+}
+
+/**
+ * Apply Redis DB index to REDIS_DB= and REDIS_URL= lines when effective.
+ *
+ * @param {string} content - .env text
+ * @param {number|null} dbIndex - from redisDbIndexForScopedRunEnv; skip if null
+ * @returns {string}
+ */
+function applyRedisDbIndexToEnvContent(content, dbIndex) {
+  if (dbIndex === null || dbIndex === undefined || typeof content !== 'string') {
+    return content;
+  }
+  const lines = content.split('\n');
+  const out = lines.map((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) return line;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1);
+    if (key === 'REDIS_DB') {
+      return `${key}=${dbIndex}`;
+    }
+    if (key === 'REDIS_URL' && value && !value.startsWith('kv://')) {
+      return `${key}=${setRedisUrlDbIndex(value, dbIndex)}`;
+    }
+    return line;
+  });
+  return out.join('\n');
+}
+
+module.exports = { applyRedisDbIndexToEnvContent, setRedisUrlDbIndex };

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

@@ -0,0 +1,204 @@
+/**
+ * Register AIFABRIX_HOME and AIFABRIX_WORK for new shells: Windows user env vars;
+ * POSIX writes a sourced script next to config.yaml and ensures a profile snippet.
+ *
+ * @fileoverview OS/shell registration after dev set-home / dev set-work
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fsp = require('node:fs').promises;
+const path = require('path');
+const os = require('os');
+const { promisify } = require('util');
+const execFileCb = require('child_process').execFile;
+const execFile = promisify(execFileCb);
+
+const { getConfigDirForPaths } = require('./paths');
+
+const SHELL_ENV_BASENAME = 'aifabrix-shell-env.sh';
+const BLOCK_BEGIN = '# BEGIN aifabrix-builder shell env';
+const BLOCK_END = '# END aifabrix-builder shell env';
+
+const PROFILE_BLOCK_RE = /\n?# BEGIN aifabrix-builder shell env\n[\s\S]*?\n# END aifabrix-builder shell env\n?/;
+
+/**
+ * Single-quote a path for POSIX export lines.
+ * @param {string} p - Path
+ * @returns {string} Quoted for sh
+ */
+function shSingleQuoted(p) {
+  const esc = String.fromCharCode(39, 92, 39, 39);
+  return `'${String(p).replace(/'/g, esc)}'`;
+}
+
+/**
+ * Build body for aifabrix-shell-env.sh (exports only; no secrets).
+ * @param {string|null} homeAbs - Resolved home or null
+ * @param {string|null} workAbs - Resolved work or null
+ * @returns {string} File content
+ */
+function buildPosixShellEnvBody(homeAbs, workAbs) {
+  const lines = ['# Managed by aifabrix dev set-home / set-work. Do not edit.'];
+  if (homeAbs) {
+    lines.push(`export AIFABRIX_HOME=${shSingleQuoted(homeAbs)}`);
+  }
+  if (workAbs) {
+    lines.push(`export AIFABRIX_WORK=${shSingleQuoted(workAbs)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Profile snippet that sources the shell env file.
+ * @param {string} envFileAbs - Absolute path to aifabrix-shell-env.sh
+ * @returns {string} Block including markers
+ */
+function buildProfileBlock(envFileAbs) {
+  const q = shSingleQuoted(envFileAbs);
+  return `${BLOCK_BEGIN}
+[ -f ${q} ] && . ${q}
+${BLOCK_END}
+`;
+}
+
+/**
+ * Resolve YAML path string to absolute or null.
+ * @param {*} raw - Config value
+ * @returns {string|null}
+ */
+function absFromConfigRaw(raw) {
+  if (typeof raw !== 'string') return null;
+  const t = raw.trim();
+  if (!t) return null;
+  return path.resolve(t);
+}
+
+/**
+ * PowerShell to set or remove a user-scoped environment variable.
+ * @param {string} name - Var name (caller must pass safe identifiers only)
+ * @param {string|null} value - Absolute path or null to remove
+ * @returns {string} PowerShell -Command argument body
+ */
+function psSetUserEnvStatement(name, value) {
+  if (value === null || value === undefined || value === '') {
+    return `[System.Environment]::SetEnvironmentVariable('${name}', $null, 'User')`;
+  }
+  const escaped = String(value).replace(/'/g, '\'\'');
+  return `[System.Environment]::SetEnvironmentVariable('${name}', '${escaped}', 'User')`;
+}
+
+/**
+ * Default rc file to patch (zsh vs bash).
+ * @param {string} homedir - User home
+ * @returns {string} Absolute profile path
+ */
+function defaultProfilePath(homedir) {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) {
+    return path.join(homedir, '.zshrc');
+  }
+  return path.join(homedir, '.bashrc');
+}
+
+/**
+ * Ensure ~/.zshrc or ~/.bashrc contains a single marked block sourcing envFileAbs.
+ * @param {string} envFileAbs - Shell env file
+ * @param {object} [overrides] - Test hooks
+ * @param {string} [overrides.profilePath] - Profile file to edit
+ * @param {string} [overrides.homedir] - Home directory
+ * @returns {Promise<void>}
+ */
+async function ensureProfileShellBlock(envFileAbs, overrides = {}) {
+  const homedir = overrides.homedir ?? os.homedir();
+  const profilePath = overrides.profilePath ?? defaultProfilePath(homedir);
+  const snippet = buildProfileBlock(envFileAbs);
+  let existing = '';
+  try {
+    existing = await fsp.readFile(profilePath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw err;
+    }
+  }
+  if (PROFILE_BLOCK_RE.test(existing)) {
+    const next = existing.replace(PROFILE_BLOCK_RE, `\n${snippet.trimEnd()}\n`);
+    if (next !== existing) {
+      await fsp.writeFile(profilePath, next, 'utf8');
+    }
+    return;
+  }
+  const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+  await fsp.writeFile(profilePath, `${existing}${sep}${snippet}`, 'utf8');
+}
+
+/**
+ * Apply Windows user env for both vars from current config (independent clear per key).
+ * @param {string|null} homeAbs
+ * @param {string|null} workAbs
+ * @param {Function} [execFileImpl] - execFile (for tests)
+ * @returns {Promise<void>}
+ */
+async function applyWindowsUserEnv(homeAbs, workAbs, execFileImpl = execFile) {
+  const script = `${psSetUserEnvStatement('AIFABRIX_HOME', homeAbs)}; ${psSetUserEnvStatement(
+    'AIFABRIX_WORK',
+    workAbs
+  )}`;
+  await execFileImpl(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-Command', script],
+    { windowsHide: true }
+  );
+}
+
+/**
+ * Write POSIX shell env file and ensure profile sources it.
+ * @param {string|null} homeAbs
+ * @param {string|null} workAbs
+ * @param {object} overrides - Test hooks (same as ensureProfileShellBlock + getConfigDirForPaths)
+ * @returns {Promise<void>}
+ */
+async function applyPosixShellEnv(homeAbs, workAbs, overrides = {}) {
+  const configDir = overrides.getConfigDirForPaths ? overrides.getConfigDirForPaths() : getConfigDirForPaths();
+  const envFile = path.join(configDir, SHELL_ENV_BASENAME);
+  await fsp.mkdir(configDir, { recursive: true });
+  const body = buildPosixShellEnvBody(homeAbs, workAbs);
+  await fsp.writeFile(envFile, body, { mode: 0o600, flag: 'w' });
+  await ensureProfileShellBlock(path.resolve(envFile), overrides);
+}
+
+/**
+ * Sync user/shell environment from saved config.yaml (after set-home or set-work).
+ *
+ * @async
+ * @param {function(): Promise<object>} getConfigFn - Same as config.getConfig
+ * @param {object} [overrides] - Optional { platform, execFile, getConfigDirForPaths, profilePath, homedir }
+ * @returns {Promise<void>}
+ */
+async function registerAifabrixShellEnvFromConfig(getConfigFn, overrides = {}) {
+  const platform = overrides.platform ?? process.platform;
+  const config = await getConfigFn();
+  const homeAbs = absFromConfigRaw(config['aifabrix-home']);
+  const workAbs = absFromConfigRaw(config['aifabrix-work']);
+
+  if (platform === 'win32') {
+    await applyWindowsUserEnv(homeAbs, workAbs, overrides.execFile || execFile);
+    return;
+  }
+
+  await applyPosixShellEnv(homeAbs, workAbs, overrides);
+}
+
+module.exports = {
+  registerAifabrixShellEnvFromConfig,
+  buildPosixShellEnvBody,
+  buildProfileBlock,
+  shSingleQuoted,
+  psSetUserEnvStatement,
+  ensureProfileShellBlock,
+  SHELL_ENV_BASENAME,
+  BLOCK_BEGIN,
+  BLOCK_END
+};

package/lib/utils/remote-builder-validation.js

@@ -0,0 +1,99 @@
+/**
+ * Remote shared builder vs local Docker Desktop — developer-id rules (plan 018).
+ *
+ * @fileoverview Fail fast when remote-server is non-localhost but developer-id is not a positive integer
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {string|null|undefined} remoteServer - remote-server from config (URL or host)
+ * @returns {boolean} True when hostname is set and not localhost / loopback only
+ */
+function remoteServerHostIsNonLocalhost(remoteServer) {
+  const raw =
+    remoteServer === null || remoteServer === undefined ? '' : String(remoteServer).trim();
+  if (!raw) {
+    return false;
+  }
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`;
+    const u = new URL(withScheme);
+    let h = (u.hostname || '').toLowerCase();
+    if (h.startsWith('[') && h.endsWith(']')) {
+      h = h.slice(1, -1);
+    }
+    if (!h) {
+      return false;
+    }
+    if (h === 'localhost' || h === '127.0.0.1' || h === '::1') {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Host for user-facing messages (no path, no credentials).
+ * @param {string|null|undefined} remoteServer
+ * @returns {string}
+ */
+function remoteServerDisplayHost(remoteServer) {
+  const raw =
+    remoteServer === null || remoteServer === undefined ? '' : String(remoteServer).trim();
+  if (!raw) {
+    return '(remote-server)';
+  }
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`;
+    const u = new URL(withScheme);
+    return u.host || raw;
+  } catch {
+    return raw;
+  }
+}
+
+const REMOTE_DEV_ID_BODY =
+  'Remote builder at %s requires a positive developer-id (1, 2, 3, …).\n' +
+  'Developer-id 0 is only supported for local Docker Desktop (localhost).\n' +
+  'Set developer-id in ~/.aifabrix/config.yaml to match your dev account (e.g. 1 for dev01), ' +
+  'or run onboarding against the builder: aifabrix dev init …';
+
+const REMOTE_DEV_ID_TAIL =
+  '\n\nIf you meant to work only on this machine, set remote-server to use localhost or remove the shared builder URL.';
+
+/**
+ * When remote-server points at a shared (non-local) builder, require developer-id ≥ 1.
+ * @param {string|null|undefined} remoteServer
+ * @param {string|number|null|undefined} developerIdRaw
+ * @throws {Error} When remote builder and id missing, non-numeric, or < 1
+ */
+function assertRemoteBuilderDeveloperId(remoteServer, developerIdRaw) {
+  if (!remoteServerHostIsNonLocalhost(remoteServer)) {
+    return;
+  }
+  const host = remoteServerDisplayHost(remoteServer);
+  const head = REMOTE_DEV_ID_BODY.replace('%s', host);
+
+  if (developerIdRaw === null || developerIdRaw === undefined || developerIdRaw === '') {
+    throw new Error(head + REMOTE_DEV_ID_TAIL);
+  }
+  const s = String(developerIdRaw).trim();
+  if (!/^\d+$/.test(s)) {
+    throw new Error(head + REMOTE_DEV_ID_TAIL);
+  }
+  const n = parseInt(s, 10);
+  if (n < 1) {
+    throw new Error(head + REMOTE_DEV_ID_TAIL);
+  }
+}
+
+module.exports = {
+  remoteServerHostIsNonLocalhost,
+  remoteServerDisplayHost,
+  assertRemoteBuilderDeveloperId
+};

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

@@ -4,35 +4,131 @@
  * @version 2.0.0
  */
 
+const path = require('path');
 const config = require('../core/config');
-const { getCertDir, readClientCertPem } = require('./dev-cert-helper');
-const { getConfigDirForPaths } = require('./paths');
+const { getCertDir, readClientCertPem, readServerCaPem } = require('./dev-cert-helper');
+const { getConfigDirForPaths, getAifabrixHome, getAifabrixWork } = require('./paths');
 
 /**
- * Check if a string is an http(s) URL (for aifabrix-secrets remote mode).
- * @param {string} value - Config value
+ * Single API object so resolveSharedSecretsEndpoint and callers share one getRemoteDevAuth
+ * (Jest spies and partial mocks work reliably).
+ */
+const remoteDevAuth = {
+  /**
+   * Check if a string is an http(s) URL (for aifabrix-secrets remote mode).
+   * @param {string} value - Config value
+   * @returns {boolean}
+   */
+  isRemoteSecretsUrl(value) {
+    return typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+  },
+
+  /**
+   * Get Builder Server URL, client cert PEM, and optional dev root CA when remote is configured; otherwise null.
+   * serverCaPem comes from ca.pem (saved at dev init); required for Node TLS to private-CA servers.
+   * Use for cert-authenticated dev API calls (settings, users, ssh-keys, secrets).
+   * @returns {Promise<{ serverUrl: string, clientCertPem: string, serverCaPem: string|null }|null>}
+   */
+  async getRemoteDevAuth() {
+    const serverUrl = await config.getRemoteServer();
+    if (!serverUrl) return null;
+    const devId = await config.getDeveloperId();
+    const certDir = getCertDir(getConfigDirForPaths(), devId);
+    const clientCertPem = readClientCertPem(certDir);
+    if (!clientCertPem) return null;
+    const serverCaPem = readServerCaPem(certDir);
+    return { serverUrl, clientCertPem, serverCaPem };
+  },
+
+  /**
+   * Resolve where shared secrets read/write should go. After dev init, config may still hold a
+   * server-side filesystem path from GET /api/dev/settings (not an http URL) if merge did not rewrite it.
+   * Those paths are not writable on the developer machine; use the Builder secrets API instead when
+   * remote-server + client cert are configured and the path is not under aifabrix-home or aifabrix-work.
+   *
+   * @param {string} configuredPath - config.yaml aifabrix-secrets
+   * @returns {Promise<string>} Same string for local file targets, or https?://…/api/dev/secrets for remote API
+   */
+  async resolveSharedSecretsEndpoint(configuredPath) {
+    if (!configuredPath || typeof configuredPath !== 'string') return configuredPath;
+    const trimmed = configuredPath.trim();
+    if (!trimmed) return configuredPath;
+    if (remoteDevAuth.isRemoteSecretsUrl(trimmed)) return trimmed.replace(/\/+$/, '');
+    const auth = await remoteDevAuth.getRemoteDevAuth();
+    if (!auth) return configuredPath;
+    const abs = normalizeSharedSecretsFilePath(trimmed);
+    if (!abs) return configuredPath;
+    const home = path.normalize(getAifabrixHome());
+    if (isPathUnderDir(abs, home)) return configuredPath;
+    const work = getAifabrixWork();
+    if (work) {
+      const w = path.normalize(work);
+      if (isPathUnderDir(abs, w)) return configuredPath;
+    }
+    const base = String(auth.serverUrl).replace(/\/+$/, '');
+    return `${base}/api/dev/secrets`;
+  },
+
+  /**
+   * Hostname from a resolved shared-secrets API URL (for CLI labels).
+   * @param {string} secretsEndpointUrl - e.g. https://builder02.local/api/dev/secrets
+   * @returns {string|null} Hostname, or null if the URL cannot be parsed
+   */
+  getSharedSecretsRemoteHostname(secretsEndpointUrl) {
+    try {
+      const u = new URL(String(secretsEndpointUrl));
+      return u.hostname || null;
+    } catch {
+      return null;
+    }
+  },
+
+  /**
+   * Titles/messages for `secret list --shared` when the store is remote.
+   * @param {string} secretsEndpointUrl - Resolved secrets API URL
+   * @returns {{ title: string, emptyMessage: string }}
+   */
+  getSharedSecretsRemoteListLabels(secretsEndpointUrl) {
+    const host = remoteDevAuth.getSharedSecretsRemoteHostname(secretsEndpointUrl);
+    if (host) {
+      return {
+        title: `Shared secrets (remote - ${host})`,
+        emptyMessage: `No shared secrets (remote - ${host}).`
+      };
+    }
+    return {
+      title: 'Shared secrets (remote)',
+      emptyMessage: 'No shared secrets (remote).'
+    };
+  }
+};
+
+/**
+ * True when normalized file path is dir or a descendant of base (same volume semantics as path relative checks).
+ * @param {string} filePath - Normalized absolute path
+ * @param {string} baseDir - Normalized absolute directory
  * @returns {boolean}
  */
-function isRemoteSecretsUrl(value) {
-  return typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://'));
+function isPathUnderDir(filePath, baseDir) {
+  if (!filePath || !baseDir) return false;
+  const f = filePath;
+  const d = baseDir;
+  if (f === d) return true;
+  const prefix = d.endsWith(path.sep) ? d : d + path.sep;
+  return f.startsWith(prefix);
 }
 
 /**
- * Get Builder Server URL and client cert PEM when remote is configured; otherwise null.
- * Use for cert-authenticated dev API calls (settings, users, ssh-keys, secrets).
- * @returns {Promise<{ serverUrl: string, clientCertPem: string }|null>}
+ * Normalize configured shared-secrets file path for "is this on the laptop?" checks.
+ * @param {string} configured - Raw config value
+ * @returns {string} Absolute normalized path
  */
-async function getRemoteDevAuth() {
-  const serverUrl = await config.getRemoteServer();
-  if (!serverUrl) return null;
-  const devId = await config.getDeveloperId();
-  const certDir = getCertDir(getConfigDirForPaths(), devId);
-  const clientCertPem = readClientCertPem(certDir);
-  if (!clientCertPem) return null;
-  return { serverUrl, clientCertPem };
+function normalizeSharedSecretsFilePath(configured) {
+  const trimmed = String(configured || '').trim();
+  if (!trimmed) return '';
+  return path.isAbsolute(trimmed)
+    ? path.normalize(trimmed)
+    : path.normalize(path.resolve(process.cwd(), trimmed));
 }
 
-module.exports = {
-  isRemoteSecretsUrl,
-  getRemoteDevAuth
-};
+module.exports = remoteDevAuth;