@aifabrix/builder 2.42.1 → 2.44.0

package/lib/utils/dev-hosts-helper.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview Optional hosts-file helper for dev init: map Builder Server hostname to an IP on this machine.
+ * Wildcard DNS (*.host) is documented for router/DNS; hosts file only supports exact hostnames (OS limitation).
+ * Writing hosts usually requires administrator rights on Windows and macOS.
+ *
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const dns = require('dns').promises;
+const path = require('path');
+const readline = require('readline');
+const chalk = require('chalk');
+const { nodeFs } = require('../internal/node-fs');
+
+const IPV4_RE = /^(25[0-5]|2[0-4]\d|1\d{2}|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d{2}|[1-9]?\d)){3}$/;
+
+/**
+ * @param {string} url - https://builder02.local or similar
+ * @returns {string} Hostname only
+ */
+function hostnameFromServerUrl(url) {
+  try {
+    return new URL(url.trim()).hostname;
+  } catch {
+    throw new Error('Invalid --server URL for hosts setup');
+  }
+}
+
+/**
+ * @param {string} s
+ * @returns {boolean}
+ */
+function isValidIpv4(s) {
+  return typeof s === 'string' && IPV4_RE.test(s.trim());
+}
+
+/**
+ * Path to system hosts file.
+ * @returns {string}
+ */
+function getHostsFilePath() {
+  if (process.platform === 'win32') {
+    const windir = process.env.WINDIR || process.env.SystemRoot || 'C:\\Windows';
+    return path.join(windir, 'System32', 'drivers', 'etc', 'hosts');
+  }
+  return '/etc/hosts';
+}
+
+/**
+ * Hostnames to map to the Builder Server IP: the URL host plus devNN.url-host for
+ * per-developer subdomains. Wildcards (*.zone) are not supported by OS hosts files.
+ * @param {string|undefined} developerId - e.g. "02"
+ * @param {string} primaryHostname - Hostname from --server (e.g. builder02.local)
+ * @returns {string[]} Deduped list (primary first, then per-dev if applicable)
+ */
+function hostsNamesForDevInit(developerId, primaryHostname) {
+  const primary = String(primaryHostname || '').trim();
+  if (!primary) return [];
+  const names = [primary];
+  const id = developerId !== undefined && developerId !== null ? String(developerId).trim() : '';
+  if (!id || isValidIpv4(primary)) return names;
+  if (/^dev\d+\./i.test(primary)) return names;
+  const perDev = `dev${id}.${primary}`;
+  if (perDev !== primary && !names.includes(perDev)) names.push(perDev);
+  return names;
+}
+
+/**
+ * Display URL for the per-developer host (devNN.zone), same scheme and port as --server.
+ * @param {string|undefined} developerId
+ * @param {string} baseUrl - Builder Server URL
+ * @returns {string|null} e.g. https://dev02.builder02.local
+ */
+function perDeveloperServerDisplayUrl(developerId, baseUrl) {
+  let u;
+  try {
+    u = new URL(String(baseUrl || '').trim());
+  } catch {
+    return null;
+  }
+  const list = hostsNamesForDevInit(developerId, u.hostname);
+  if (list.length < 2) return null;
+  const perDevHost = list[1];
+  u.hostname = perDevHost;
+  const portPart = u.port ? `:${u.port}` : '';
+  return `${u.protocol}//${u.hostname}${portPart}`;
+}
+
+/**
+ * @param {{ log: function }} logger
+ * @param {string|undefined} developerId
+ * @param {string} baseUrl
+ * @returns {void}
+ */
+function logPerDeveloperUrlHint(logger, developerId, baseUrl) {
+  const displayUrl = perDeveloperServerDisplayUrl(developerId, baseUrl);
+  if (!displayUrl) return;
+  logger.log(chalk.green('  Your per-developer URL: ') + chalk.cyan(displayUrl));
+  logger.log('');
+}
+
+/**
+ * True if hosts file already maps hostname (any IP).
+ * @param {string} hostsPath
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function hostsFileHasHostname(hostsPath, hostname) {
+  const want = String(hostname || '').trim();
+  if (!want) return false;
+  let text;
+  try {
+    text = nodeFs().readFileSync(hostsPath, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return false;
+    throw e;
+  }
+  if (typeof text !== 'string') return false;
+  for (const line of text.split(/\r?\n/)) {
+    const t = line.replace(/#.*/, '').trim();
+    if (!t) continue;
+    const parts = t.split(/\s+/).filter(Boolean);
+    if (parts.length < 2) continue;
+    const names = parts.slice(1).map((n) => String(n).trim());
+    if (names.includes(want)) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+function promptLine(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve((answer || '').trim());
+    });
+  });
+}
+
+/**
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+async function promptYesNo(question) {
+  const a = (await promptLine(question)).toLowerCase();
+  return a === 'y' || a === 'yes';
+}
+
+/**
+ * Try IPv4 lookup for hostname.
+ * @param {string} hostname
+ * @returns {Promise<string|null>}
+ */
+async function lookupIpv4(hostname) {
+  try {
+    const r = await dns.lookup(hostname, { family: 4 });
+    return r.address || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Print how to add the line with admin/sudo when direct write failed.
+ * @param {{ log: function }} logger
+ * @param {string} hostsPath
+ * @param {string} line
+ */
+function printManualHostsInstructions(logger, hostsPath, line) {
+  if (process.platform === 'win32') {
+    logger.log(chalk.yellow('\n  Could not write hosts file (need Administrator). Run PowerShell as Administrator, then:\n'));
+    logger.log(chalk.cyan(`  Add-Content -Path "${hostsPath}" -Value "\`r\`n${line}\`r\`n"`));
+  } else {
+    logger.log(chalk.yellow('\n  Could not write hosts file (need elevated permissions). Run:\n'));
+    logger.log(chalk.cyan(`  echo '${line}' | sudo tee -a ${hostsPath}`));
+  }
+}
+
+/**
+ * @param {{ log: function }} logger
+ * @param {string[]} hostnames - Names we may add (URL host + optional devNN.zone)
+ */
+function logHostsIntro(logger, hostnames) {
+  const list = (hostnames && hostnames.length ? hostnames : []).join(', ');
+  logger.log(chalk.blue('\n📍 Local name resolution (optional)\n'));
+  logger.log(
+    chalk.gray(
+      '  Wildcards such as *.local are not supported in the hosts file (OS limitation). '
+      + 'Use DNS or router DNS for wildcard zones; here we add exact names only.'
+    )
+  );
+  logger.log(chalk.gray(`  Names to map to that IP (same line where possible): ${list}`));
+  logger.log('');
+}
+
+/**
+ * @param {string} hostname
+ * @param {string|undefined} hostsIp - From --hosts-ip
+ * @param {{ log: function }} logger
+ * @returns {Promise<string|null>} IPv4 or null if user skipped
+ */
+async function resolveHostsIpForInit(hostname, hostsIp, logger) {
+  let ip = typeof hostsIp === 'string' && hostsIp.trim() ? hostsIp.trim() : null;
+  if (ip && !isValidIpv4(ip)) {
+    throw new Error(`Invalid --hosts-ip: "${ip}" (use an IPv4 address, e.g. 192.168.1.25)`);
+  }
+  if (!ip) {
+    const lookedUp = await lookupIpv4(hostname);
+    if (lookedUp && isValidIpv4(lookedUp)) {
+      logger.log(chalk.gray(`  ${hostname} currently resolves to ${lookedUp} (DNS or existing hosts).`));
+      ip = lookedUp;
+    }
+  }
+  if (ip) return ip;
+  const entered = await promptLine(chalk.yellow(`  Enter IPv4 address for ${hostname} (e.g. 192.168.1.25): `));
+  if (!entered) {
+    logger.log(chalk.gray('  Skipping hosts file (no IP entered).\n'));
+    return null;
+  }
+  if (!isValidIpv4(entered)) {
+    throw new Error(`Invalid IP address: "${entered}"`);
+  }
+  return entered;
+}
+
+/**
+ * @param {string} hostsPath
+ * @param {string} block - Full text to append
+ * @param {string} line - Single-line form for manual instructions
+ * @param {{ log: function }} logger
+ * @returns {Promise<void>}
+ */
+async function appendHostsBlockOrPrintManual(hostsPath, block, line, logger) {
+  try {
+    await nodeFs().promises.appendFile(hostsPath, block, { encoding: 'utf8' });
+    logger.log(chalk.green(`  ✔ Updated ${hostsPath}\n`));
+  } catch (e) {
+    if (e.code === 'EACCES' || e.code === 'EPERM') {
+      logger.log(chalk.yellow(`  ✖ Could not write ${hostsPath} (permission denied).`));
+      printManualHostsInstructions(logger, hostsPath, line);
+      logger.log('');
+      return;
+    }
+    throw e;
+  }
+}
+
+/**
+ * @param {string} hostsPath
+ * @param {string[]} hostnames
+ * @param {string} ip
+ * @param {boolean} skipConfirm
+ * @param {{ log: function }} logger
+ * @returns {Promise<void>}
+ */
+async function tryWriteHostsEntry(hostsPath, hostnames, ip, skipConfirm, logger) {
+  const missing = hostnames.filter((h) => !hostsFileHasHostname(hostsPath, h));
+  if (missing.length === 0) {
+    logger.log(chalk.green(`  ✔ Required hostnames are already listed in ${hostsPath}. Nothing to do.\n`));
+    return;
+  }
+  const line = `${ip} ${missing.join(' ')}`;
+  logger.log(chalk.gray(`  Suggested hosts line: ${line}`));
+  const yn = chalk.yellow(`  Add this line to ${hostsPath}? This may require administrator approval. (y/n) `);
+  const confirm = skipConfirm || (await promptYesNo(yn));
+  if (!confirm) {
+    logger.log(chalk.gray('  Skipping hosts file update.\n'));
+    return;
+  }
+  const block = `\n# aifabrix dev init — ${missing.join(', ')}\n${line}\n`;
+  await appendHostsBlockOrPrintManual(hostsPath, block, line, logger);
+}
+
+/**
+ * Optional hosts setup for dev init (--add-hosts).
+ * @param {Object} params
+ * @param {string} params.baseUrl - Builder Server URL
+ * @param {string} [params.developerId] - From --developer-id (adds devNN.hostname)
+ * @param {string} [params.hostsIp] - From --hosts-ip
+ * @param {boolean} params.skipConfirm - When true (-y), append without y/n
+ * @param {{ log: function }} params.logger - logger like lib/utils/logger
+ * @returns {Promise<void>}
+ */
+async function runOptionalHostsSetup({ baseUrl, developerId, hostsIp, skipConfirm, logger }) {
+  const primary = hostnameFromServerUrl(baseUrl);
+  const hostnames = hostsNamesForDevInit(developerId, primary);
+  logHostsIntro(logger, hostnames);
+  const ip = await resolveHostsIpForInit(primary, hostsIp, logger);
+  if (ip === null) return;
+  await tryWriteHostsEntry(getHostsFilePath(), hostnames, ip, skipConfirm, logger);
+  logPerDeveloperUrlHint(logger, developerId, baseUrl);
+}
+
+module.exports = {
+  hostnameFromServerUrl,
+  hostsNamesForDevInit,
+  perDeveloperServerDisplayUrl,
+  isValidIpv4,
+  getHostsFilePath,
+  hostsFileHasHostname,
+  runOptionalHostsSetup
+};

package/lib/utils/dev-init-cert-hints.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Cert troubleshooting hints for dev init (keeps dev-init.js under max-lines).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const chalk = require('chalk');
+const { getCertDir } = require('./dev-cert-helper');
+const logger = require('./logger');
+
+/**
+ * Message for 400 Bad Request: nginx often forwards X-Client-Cert with literal newlines.
+ * @returns {string} Hint for server-side nginx fix
+ */
+function getBadRequestHint() {
+  return 'Bad Request (400) often means the server\'s nginx is forwarding the client certificate with literal newlines in X-Client-Cert. On the server, use nginx njs to escape newlines (see .cursor/plans/builder-cli.md §5).';
+}
+
+/**
+ * Log a one-line hint for cert troubleshooting (curl test and docs).
+ * @param {string} configDir - Config directory
+ * @param {string} devId - Developer ID
+ * @param {string} baseUrl - Builder Server base URL
+ */
+function logCertTroubleshootingHint(configDir, devId, baseUrl) {
+  const certDir = getCertDir(configDir, devId);
+  const certPath = path.join(certDir, 'cert.pem');
+  const keyPath = path.join(certDir, 'key.pem');
+  logger.log(chalk.gray(`  Test with: curl -v --cert ${certPath} --key ${keyPath} ${baseUrl}/api/dev/settings`));
+  logger.log(chalk.gray('  See .cursor/plans/builder-cli.md §5 for 200 vs 401 vs 400 and nginx/server fix.'));
+}
+
+module.exports = {
+  getBadRequestHint,
+  logCertTroubleshootingHint
+};

package/lib/utils/dev-init-health-messages.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Health / TLS failure messages for dev init (keeps dev-init.js under max-lines).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { isLinuxCaSudoRequiredError } = require('./dev-ca-install');
+
+/**
+ * True when /health returned a 5xx (server or gateway error). TLS succeeded; app may still be degraded.
+ * @param {Error} err - Thrown from getHealth
+ * @returns {boolean}
+ */
+function isHealthHttpServerError(err) {
+  const s = err && typeof err.status === 'number' ? err.status : null;
+  return s !== null && s >= 500 && s < 600;
+}
+
+/**
+ * Message when trust/health step fails (avoid calling HTTP 5xx "cannot reach").
+ * @param {string} baseUrl - Builder Server URL
+ * @param {Error} err - Failure from getHealth or TLS
+ * @returns {string}
+ */
+function formatEnsureServerTrustedFailure(baseUrl, err) {
+  const s = err && typeof err.status === 'number' ? err.status : null;
+  if (s !== null) {
+    const detail = err.message || `HTTP ${s}`;
+    if (s >= 500 && s < 600) {
+      return (
+        `Builder Server at ${baseUrl} returned HTTP ${s} (${detail}) on GET /health. ` +
+        'TLS succeeded; the service reported an error or is not fully healthy. Check server logs or open /health in a browser.'
+      );
+    }
+    return (
+      `Builder Server at ${baseUrl} returned HTTP ${s} (${detail}) on GET /health. ` +
+      'The host was reached but health did not succeed. Check the URL and server configuration.'
+    );
+  }
+  if (isLinuxCaSudoRequiredError(err)) {
+    return (
+      `Could not add the development CA to the system trust store for ${baseUrl} (Linux needs sudo for that step). ` +
+      `${err.message}`
+    );
+  }
+  return `Cannot reach Builder Server at ${baseUrl}. Check URL and network. ${err.message}`;
+}
+
+module.exports = {
+  isHealthHttpServerError,
+  formatEnsureServerTrustedFailure
+};

package/lib/utils/dev-init-resolve.js

@@ -0,0 +1,86 @@
+/**
+ * Resolve Builder URL, developer id, and PIN for dev init.
+ * CLI flags override config. Developer id from config is not used when it is "0" (local default).
+ *
+ * @fileoverview Shared onboarding option resolution for dev-init command
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const config = require('../core/config');
+
+function requirePin(options) {
+  const pin = options.pin;
+  if (!pin || typeof pin !== 'string' || !pin.trim()) {
+    throw new Error(
+      '--pin is required (one-time PIN). On an enrolled admin PC run: aifabrix dev pin <developer-id>, ' +
+        'then use the PIN on this machine.'
+    );
+  }
+}
+
+/**
+ * @param {Object} options - Commander options
+ * @returns {Promise<{ devId: string, devIdFromConfig: boolean }>}
+ */
+async function resolveDeveloperIdPart(options) {
+  const rawOptDev = options.developerId ?? options['developer-id'];
+  let devId;
+  let devIdFromConfig = false;
+  if (rawOptDev !== undefined && rawOptDev !== null && String(rawOptDev).trim() !== '') {
+    devId = String(rawOptDev).trim();
+  } else {
+    const fromCfg = await config.getDeveloperId();
+    devId = fromCfg !== undefined && fromCfg !== null ? String(fromCfg).trim() : '';
+    devIdFromConfig = true;
+  }
+
+  if (!devId || !/^[0-9]+$/.test(devId)) {
+    throw new Error(
+      'Pass --developer-id <id> (digits only) or set developer-id in config (aifabrix dev set-id <id>).'
+    );
+  }
+
+  if (devIdFromConfig && devId === '0') {
+    throw new Error(
+      'Cannot use default developer-id 0 from config for Builder onboarding. Pass --developer-id <id> (e.g. 02) or run aifabrix dev set-id first.'
+    );
+  }
+
+  return { devId, devIdFromConfig };
+}
+
+/**
+ * @param {Object} options - Commander options
+ * @returns {Promise<string>} Normalized base URL (no trailing slash)
+ */
+async function resolveServerBaseUrl(options) {
+  let server = options.server;
+  if (!server || typeof server !== 'string' || !String(server).trim()) {
+    const fromCfg = await config.getRemoteServer();
+    server = fromCfg && typeof fromCfg === 'string' ? fromCfg.trim() : '';
+  } else {
+    server = String(server).trim();
+  }
+
+  if (!server) {
+    throw new Error(
+      'Pass --server <Builder URL> or set remote-server in ~/.aifabrix/config.yaml (from settings merge or aifabrix dev show).'
+    );
+  }
+
+  return server.replace(/\/+$/, '');
+}
+
+/**
+ * @param {Object} options - Commander options
+ * @returns {Promise<{ baseUrl: string, devId: string }>}
+ */
+async function resolveInitOptions(options) {
+  requirePin(options);
+  const { devId } = await resolveDeveloperIdPart(options);
+  const baseUrl = await resolveServerBaseUrl(options);
+  return { baseUrl, devId };
+}
+
+module.exports = { resolveInitOptions };

package/lib/utils/dev-init-ssh-merge.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview After dev init: merge SSH config Host alias from sync settings / server URL.
+ */
+
+const chalk = require('chalk');
+const config = require('../core/config');
+const logger = require('./logger');
+const { ensureDevSshConfigBlock } = require('./dev-ssh-config-helper');
+
+/**
+ * Hostname from Builder Server URL (for sync-ssh-host fallback).
+ * @param {string} baseUrl - e.g. https://builder02.local
+ * @returns {string|null}
+ */
+function hostnameFromBaseUrl(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== 'string') return null;
+  const s = baseUrl.trim().replace(/\/+$/, '');
+  const withProtocol = /^https?:\/\//i.test(s) ? s : `https://${s}`;
+  try {
+    return new URL(withProtocol).hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Update ~/.ssh/config with Host <user>.<host> for interactive SSH; log result.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} devId - Developer ID (digits)
+ * @returns {Promise<{ hostAlias: string|null, syncUser: string, syncHost: string|null }>}
+ */
+async function mergeDevSshConfigAfterInit(baseUrl, devId) {
+  const syncHost = (await config.getSyncSshHost()) || hostnameFromBaseUrl(baseUrl);
+  const syncUser = (await config.getSyncSshUser()) || `dev${devId}`;
+  if (!syncHost) {
+    return { hostAlias: null, syncUser, syncHost: null };
+  }
+  try {
+    const res = await ensureDevSshConfigBlock(syncUser, syncHost);
+    if (res.ok && res.configPath && res.hostAlias) {
+      if (res.skippedDuplicate) {
+        logger.log(
+          chalk.gray('  SSH config already has ') +
+            chalk.cyan(`${syncUser}@${syncHost}`) +
+            chalk.gray(` (Host ${res.hostAlias}); left unchanged.`)
+        );
+      } else {
+        logger.log(
+          chalk.green('  ✔ SSH config updated: ') +
+            chalk.cyan(`Host ${res.hostAlias}`) +
+            chalk.gray(` → ${res.configPath}`)
+        );
+      }
+      return { hostAlias: res.hostAlias, syncUser, syncHost };
+    }
+    if (!res.ok && res.error) {
+      logger.log(chalk.yellow(`  ⚠ Could not update SSH config: ${res.error}`));
+    }
+  } catch (e) {
+    logger.log(chalk.yellow(`  ⚠ Could not update SSH config: ${e.message || e}`));
+  }
+  return { hostAlias: null, syncUser, syncHost };
+}
+
+module.exports = { mergeDevSshConfigAfterInit, hostnameFromBaseUrl };