@aifabrix/builder 2.49.1 → 2.50.0

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

@@ -2,10 +2,17 @@
  * @fileoverview After dev init: merge SSH config Host alias from sync settings / server URL.
  */
 
+const path = require('path');
 const chalk = require('chalk');
 const config = require('../core/config');
 const logger = require('./logger');
-const { ensureDevSshConfigBlock } = require('./dev-ssh-config-helper');
+const { ensureDevSshConfigBlock, listHostAliasesForUserHost } = require('./dev-ssh-config-helper');
+const { ensureSshDir } = require('./ssh-key-helper');
+const { nodeFs } = require('../internal/node-fs');
+const {
+  collectDevSshKnownHostCandidates,
+  refreshDevSshKnownHosts
+} = require('./ssh-known-hosts');
 const { successGlyph } = require('./cli-layout-chalk');
 
 /**
@@ -24,6 +31,134 @@ function hostnameFromBaseUrl(baseUrl) {
   }
 }
 
+/**
+ * @param {string} sshDir
+ * @returns {Promise<string>}
+ */
+async function readSshConfigContent(sshDir) {
+  const configPath = path.join(ensureSshDir(sshDir), 'config');
+  try {
+    return await nodeFs().promises.readFile(configPath, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      return '';
+    }
+    throw e;
+  }
+}
+
+/**
+ * @param {Object} p
+ * @param {string} p.baseUrl
+ * @param {string} p.syncHost
+ * @param {string} p.syncUser
+ * @param {string} p.hostAlias
+ * @param {string} p.existingSshConfig
+ * @param {string|number} [p.developerId]
+ * @param {string} [p.developerRootDomain]
+ * @returns {Promise<void>}
+ */
+async function refreshKnownHostsForDevSsh(p) {
+  const legacyHostAliases = listHostAliasesForUserHost(
+    p.existingSshConfig,
+    p.syncHost,
+    p.syncUser
+  );
+  const candidates = collectDevSshKnownHostCandidates({
+    syncHost: p.syncHost,
+    syncUser: p.syncUser,
+    hostAlias: p.hostAlias,
+    baseUrl: p.baseUrl,
+    developerId: p.developerId,
+    developerRootDomain: p.developerRootDomain,
+    legacyHostAliases
+  });
+  const { cleared, failed } = await refreshDevSshKnownHosts(candidates);
+  if (cleared.length > 0) {
+    logger.log(
+      `${chalk.green('  ')}${successGlyph()}${chalk.green(' Cleared stale SSH host keys for ')}` +
+        chalk.cyan(cleared.join(', ')) +
+        chalk.gray(' (accept the new key on first connect if prompted).')
+    );
+  }
+  if (failed.some((row) => row.error === 'ssh-keygen not found')) {
+    logger.log(
+      chalk.yellow(
+        '  ⚠ ssh-keygen not found; if SSH reports "REMOTE HOST IDENTIFICATION HAS CHANGED", ' +
+          `run: ssh-keygen -R ${p.syncHost}`
+      )
+    );
+  }
+}
+
+/**
+ * @param {string|undefined} developerRootDomain
+ * @returns {string|undefined}
+ */
+function trimDeveloperRootDomain(developerRootDomain) {
+  const trimmed = developerRootDomain && String(developerRootDomain).trim();
+  return trimmed || undefined;
+}
+
+/**
+ * @param {Object} res
+ * @param {string} syncUser
+ * @param {string} syncHost
+ * @returns {void}
+ */
+function logSshConfigMergeResult(res, syncUser, syncHost) {
+  if (res.skippedDuplicate) {
+    logger.log(
+      chalk.gray('  SSH config already has ') +
+        chalk.cyan(`${syncUser}@${syncHost}`) +
+        chalk.gray(` (Host ${res.hostAlias}); left unchanged.`)
+    );
+    return;
+  }
+  const prefix =
+    `${chalk.green('  ')}${successGlyph()}${chalk.green(' SSH config updated: ')}` +
+    chalk.cyan(`Host ${res.hostAlias}`);
+  const suffix = res.migratedFrom
+    ? chalk.gray(` (was ${res.migratedFrom}) → ${res.configPath}`)
+    : chalk.gray(` → ${res.configPath}`);
+  logger.log(prefix + suffix);
+}
+
+/**
+ * @param {Object} p
+ * @param {string} p.baseUrl
+ * @param {string} p.devId
+ * @param {string} p.syncUser
+ * @param {string} p.syncHost
+ * @param {string|undefined} p.rootTrimmed
+ * @returns {Promise<{ hostAlias: string|null, syncUser: string, syncHost: string }>}
+ */
+async function mergeDevSshConfigBlock(p) {
+  const sshDir = ensureSshDir();
+  const existingSshConfig = await readSshConfigContent(sshDir);
+  const res = await ensureDevSshConfigBlock(p.syncUser, p.syncHost, sshDir, {
+    developerId: p.devId,
+    developerRootDomain: p.rootTrimmed
+  });
+  if (!res.ok || !res.configPath || !res.hostAlias) {
+    if (!res.ok && res.error) {
+      logger.log(chalk.yellow(`  ⚠ Could not update SSH config: ${res.error}`));
+    }
+    return { hostAlias: null, syncUser: p.syncUser, syncHost: p.syncHost };
+  }
+  await refreshKnownHostsForDevSsh({
+    baseUrl: p.baseUrl,
+    syncHost: p.syncHost,
+    syncUser: p.syncUser,
+    hostAlias: res.hostAlias,
+    existingSshConfig,
+    developerId: p.devId,
+    developerRootDomain: p.rootTrimmed
+  });
+  logSshConfigMergeResult(res, p.syncUser, p.syncHost);
+  return { hostAlias: res.hostAlias, syncUser: p.syncUser, syncHost: p.syncHost };
+}
+
 /**
  * Update ~/.ssh/config with Host <user>.<host> for interactive SSH; log result.
  * @param {string} baseUrl - Builder Server base URL
@@ -37,30 +172,37 @@ async function mergeDevSshConfigAfterInit(baseUrl, devId) {
     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('  ')}${successGlyph()}${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}`));
-    }
+    const rootTrimmed = trimDeveloperRootDomain(await config.getDeveloperRootDomain());
+    return await mergeDevSshConfigBlock({
+      baseUrl,
+      devId,
+      syncUser,
+      syncHost,
+      rootTrimmed
+    });
   } catch (e) {
     logger.log(chalk.yellow(`  ⚠ Could not update SSH config: ${e.message || e}`));
+    return { hostAlias: null, syncUser, syncHost };
+  }
+}
+
+/**
+ * @param {{ hostAlias: string|null }} sshInfo
+ * @returns {void}
+ */
+function logDevSshConnectHint(sshInfo) {
+  if (!sshInfo || !sshInfo.hostAlias) {
+    return;
   }
-  return { hostAlias: null, syncUser, syncHost };
+  logger.log(
+    chalk.gray('  SSH: ') +
+      chalk.cyan(`ssh ${sshInfo.hostAlias}`) +
+      chalk.gray(' (host keys refreshed if the server was reprovisioned).')
+  );
 }
 
-module.exports = { mergeDevSshConfigAfterInit, hostnameFromBaseUrl };
+module.exports = {
+  mergeDevSshConfigAfterInit,
+  logDevSshConnectHint,
+  hostnameFromBaseUrl
+};

package/lib/utils/dev-pin-share-instructions.js

@@ -0,0 +1,110 @@
+/**
+ * Copy-paste onboarding block for `aifabrix dev pin` (admin → developer).
+ *
+ * @fileoverview Dev PIN share instructions with platform prerequisites
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { formatSuccessLine } = require('./cli-test-layout-chalk');
+
+const NODE_INSTALL_URL = 'https://nodejs.org/';
+const BUILDER_INSTALL_CMD = 'npm install -g @aifabrix/builder';
+
+/**
+ * @returns {void}
+ */
+function logDevPinPrerequisites() {
+  logger.log(chalk.bold('Prerequisites (once per machine):'));
+  logger.log('');
+  logger.log(chalk.cyan('Windows'));
+  logger.log(chalk.gray(`  1. Install Node.js 18+ from ${NODE_INSTALL_URL}`));
+  logger.log(`  2. ${BUILDER_INSTALL_CMD}`);
+  logger.log('');
+  logger.log(chalk.cyan('Linux & macOS'));
+  logger.log(
+    chalk.gray(`  1. Install Node.js 18+ (${NODE_INSTALL_URL} or your package manager)`)
+  );
+  logger.log(`  2. ${BUILDER_INSTALL_CMD}`);
+  logger.log('');
+  logger.log(chalk.gray('  After install, `af` is a shortcut for `aifabrix`.'));
+}
+
+/**
+ * @param {string} baseInit
+ * @param {string} id
+ * @param {string} [hostsIp]
+ * @returns {void}
+ */
+function logPinHostsVariantLines(baseInit, id, hostsIp) {
+  logger.log(
+    chalk.cyan('2) Hosts file / administrator')
+    + chalk.gray(
+      ' — use when the hostname does not resolve and your organisation does not publish DNS for it. '
+      + 'Run in an elevated terminal so the hosts file can be updated, or add the entry manually:'
+    )
+  );
+  if (hostsIp) {
+    logger.log(`   ${baseInit} --add-hosts --hosts-ip ${hostsIp}`);
+  } else {
+    logger.log(`   ${baseInit} --add-hosts --hosts-ip <server-LAN-IPv4>`);
+    logger.log(
+      chalk.gray(
+        `   Replace <server-LAN-IPv4> with the Builder Server IPv4, or re-run: aifabrix dev pin ${id} --hosts-ip <ip>`
+      )
+    );
+  }
+}
+
+/**
+ * Log copy-paste dev init commands for the developer (standard vs hosts-file).
+ * @param {Object} p
+ * @param {string} p.id - Developer ID
+ * @param {string} p.serverUrl - Builder Server base URL
+ * @param {string} p.pin - One-time PIN
+ * @param {string} p.expiresAt - PIN expiry (API string)
+ * @param {string} [p.hostsIp] - Optional IPv4 for the hosts variant
+ * @returns {void}
+ */
+function logDevPinShareInstructions(p) {
+  const { id, serverUrl, pin, expiresAt, hostsIp } = p;
+  const baseInit = `aifabrix dev init --developer-id ${id} --server ${serverUrl} --pin ${pin}`;
+  const pinOnly = `aifabrix dev init --pin ${pin}`;
+  logger.log(formatSuccessLine(`PIN created for ${id}, expires ${expiresAt}.`));
+  logger.log('');
+  logger.log(
+    chalk.bold('Share with the developer — prerequisites and onboarding (PIN is one-time):')
+  );
+  logger.log('');
+  logDevPinPrerequisites();
+  logger.log('');
+  logger.log(chalk.bold('Then run one command to connect (choose the variant that fits):'));
+  logger.log('');
+  logger.log(
+    chalk.cyan('1) Standard')
+    + chalk.gray(' — use when this machine can resolve the server hostname (DNS or hosts already set):')
+  );
+  logger.log(`   ${baseInit}`);
+  logger.log('');
+  logPinHostsVariantLines(baseInit, id, hostsIp);
+  logger.log('');
+  logger.log(
+    chalk.cyan('3) Config already has remote-server + developer-id')
+    + chalk.gray(
+      ' — e.g. second machine / SSH session after settings were merged; same onboarding, PIN only:'
+    )
+  );
+  logger.log(`   ${pinOnly}`);
+  logger.log('');
+}
+
+module.exports = {
+  BUILDER_INSTALL_CMD,
+  NODE_INSTALL_URL,
+  logDevPinPrerequisites,
+  logDevPinShareInstructions
+};

package/lib/utils/dev-ssh-config-helper.js

@@ -6,18 +6,49 @@
 
 const nodeFsLib = require('../internal/node-fs');
 const path = require('path');
-const { ensureSshDir } = require('./ssh-key-helper');
+const { ensureSshDir, getDefaultEd25519PrivateKeyPath } = require('./ssh-key-helper');
 
 /**
- * Derive SSH config Host alias: sync user + real hostname (e.g. dev01.builder02.local).
- * @param {string} sshUser - sync-ssh-user
- * @param {string} sshHost - sync-ssh-host (HostName)
+ * Legacy SSH Host alias: sync user + builder API hostname (e.g. dev03.builder01.aifabrix.dev).
+ * @param {string} sshUser
+ * @param {string} sshHost
  * @returns {string}
  */
 function getDevSshHostAlias(sshUser, sshHost) {
   return `${sshUser}.${sshHost}`;
 }
 
+/**
+ * @param {string|number} developerId
+ * @returns {string}
+ */
+function formatDeveloperNumericId(developerId) {
+  const trimmed = String(developerId ?? '').trim();
+  if (/^\d+$/.test(trimmed)) {
+    return String(parseInt(trimmed, 10)).padStart(2, '0');
+  }
+  return trimmed.replace(/^dev/i, '');
+}
+
+/**
+ * Preferred SSH config Host alias — matches per-developer app host when developer-root-domain is set.
+ *
+ * @param {Object} p
+ * @param {string} p.syncUser
+ * @param {string} p.syncHost - sync-ssh-host (HostName for TCP connect)
+ * @param {string|number} [p.developerId]
+ * @param {string} [p.developerRootDomain] - e.g. aifabrix.dev → dev03.aifabrix.dev; dev.aifabrix → dev03.dev.aifabrix
+ * @returns {string}
+ */
+function resolveDevSshHostAlias(p) {
+  const root = String(p.developerRootDomain || '').trim().replace(/^\.+|\.+$/g, '');
+  const id = p.developerId !== undefined && p.developerId !== null ? String(p.developerId).trim() : '';
+  if (root && id) {
+    return `dev${formatDeveloperNumericId(id)}.${root}`;
+  }
+  return getDevSshHostAlias(p.syncUser, p.syncHost);
+}
+
 /**
  * Parse ssh config into Host blocks (lines before the first Host are ignored).
  * @param {string} content
@@ -91,6 +122,48 @@ function resolveConnectAlias(matchedBlock, canonicalAlias) {
   return matchedBlock.aliases[0] || canonicalAlias;
 }
 
+/**
+ * @param {string[]} body
+ * @param {string} hostname
+ * @param {string} user
+ * @returns {boolean}
+ */
+function isSshHostBlockForUserHost(body, hostname, user) {
+  return (
+    getHostBlockDirective(body, 'HostName') === hostname &&
+    getHostBlockDirective(body, 'User') === user
+  );
+}
+
+/**
+ * Drop Host blocks that target the same HostName + User (legacy alias migration).
+ * @param {string} content
+ * @param {string} hostname
+ * @param {string} user
+ * @returns {string}
+ */
+function removeSshHostBlocksForUserHost(content, hostname, user) {
+  const lines = (content || '').split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^Host\s+(.+?)\s*$/i);
+    if (!m) {
+      out.push(lines[i]);
+      continue;
+    }
+    const body = [];
+    i++;
+    while (i < lines.length && !/^Host\s/i.test(lines[i])) {
+      body.push(lines[i++]);
+    }
+    if (!isSshHostBlockForUserHost(body, hostname, user)) {
+      out.push(`Host ${m[1].trim()}`, ...body);
+    }
+    i--;
+  }
+  return out.join('\n').replace(/\s+$/, '');
+}
+
 /**
  * Replace an existing Host block for hostAlias, or append a new block at EOF.
  * @param {string} content - Existing ssh config (may be empty)
@@ -100,7 +173,8 @@ function resolveConnectAlias(matchedBlock, canonicalAlias) {
  * @returns {string} Updated config
  */
 function upsertSshHostBlock(content, hostAlias, hostname, user) {
-  const lines = (content || '').split(/\r?\n/);
+  const withoutDupes = removeSshHostBlocksForUserHost(content, hostname, user);
+  const lines = (withoutDupes || '').split(/\r?\n/);
   const out = [];
   let i = 0;
   while (i < lines.length) {
@@ -123,6 +197,7 @@ function upsertSshHostBlock(content, hostAlias, hostname, user) {
     `Host ${hostAlias}`,
     `    HostName ${hostname}`,
     `    User ${user}`,
+    `    IdentityFile ${getDefaultEd25519PrivateKeyPath().replace(/\\/g, '/')}`,
     '    IdentitiesOnly yes'
   ].join('\n');
   const trimmed = out.join('\n').replace(/\s+$/, '');
@@ -130,12 +205,27 @@ function upsertSshHostBlock(content, hostAlias, hostname, user) {
   return `${prefix}${block}\n`;
 }
 
+function listHostAliasesForUserHost(content, hostname, user) {
+  const aliases = [];
+  for (const block of parseSshHostBlocks(content)) {
+    const hn = getHostBlockDirective(block.body, 'HostName');
+    const u = getHostBlockDirective(block.body, 'User');
+    if (hn === hostname && u === user) {
+      aliases.push(...block.aliases);
+    }
+  }
+  return aliases;
+}
+
 /**
  * @param {string} sshUser
  * @param {string} sshHost
- * @returns {{ error: string }|{ user: string, host: string, hostAlias: string }}
+ * @param {Object} [options]
+ * @param {string|number} [options.developerId]
+ * @param {string} [options.developerRootDomain]
+ * @returns {{ error: string }|{ user: string, host: string, hostAlias: string, legacyHostAlias: string }}
  */
-function parseEnsureSshInputs(sshUser, sshHost) {
+function parseEnsureSshInputs(sshUser, sshHost, options = {}) {
   if (!sshUser || typeof sshUser !== 'string' || !sshUser.trim()) {
     return { error: 'missing ssh user' };
   }
@@ -144,7 +234,53 @@ function parseEnsureSshInputs(sshUser, sshHost) {
   }
   const user = sshUser.trim();
   const host = sshHost.trim();
-  return { user, host, hostAlias: getDevSshHostAlias(user, host) };
+  const hostAlias = resolveDevSshHostAlias({
+    syncUser: user,
+    syncHost: host,
+    developerId: options.developerId,
+    developerRootDomain: options.developerRootDomain
+  });
+  return {
+    user,
+    host,
+    hostAlias,
+    legacyHostAlias: getDevSshHostAlias(user, host)
+  };
+}
+
+/**
+ * @param {string} configPath
+ * @returns {Promise<{ content: string }|{ error: string }>}
+ */
+async function readExistingSshConfig(configPath) {
+  try {
+    const content = await nodeFsLib.nodeFs().promises.readFile(configPath, 'utf8');
+    return { content };
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      return { content: '' };
+    }
+    return { error: e.message || String(e) };
+  }
+}
+
+/**
+ * @param {{ aliases: string[], body: string[] }|null} matched
+ * @param {string} hostAlias
+ * @param {string} rootDomain
+ * @returns {{ skip: true, hostAlias: string }|{ skip: false, matched: typeof matched }}
+ */
+function resolveExistingSshBlock(matched, hostAlias, rootDomain) {
+  if (!matched) {
+    return { skip: false, matched: null };
+  }
+  const matchedAlias = resolveConnectAlias(matched, hostAlias);
+  const keepExisting =
+    !rootDomain || (matched.aliases.includes(hostAlias) && matchedAlias === hostAlias);
+  if (keepExisting) {
+    return { skip: true, hostAlias: matchedAlias };
+  }
+  return { skip: false, matched };
 }
 
 /**
@@ -152,44 +288,52 @@ function parseEnsureSshInputs(sshUser, sshHost) {
  * @param {string} sshUser - SSH user (sync-ssh-user)
  * @param {string} sshHost - Real hostname (sync-ssh-host)
  * @param {string} [sshDir] - SSH directory (default ~/.ssh)
- * @returns {Promise<{ ok: boolean, configPath?: string, hostAlias?: string, error?: string, skippedDuplicate?: boolean }>}
+ * @param {Object} [options]
+ * @param {string|number} [options.developerId]
+ * @param {string} [options.developerRootDomain]
+ * @returns {Promise<{ ok: boolean, configPath?: string, hostAlias?: string, error?: string, skippedDuplicate?: boolean, updated?: boolean }>}
  */
-async function ensureDevSshConfigBlock(sshUser, sshHost, sshDir) {
-  const parsed = parseEnsureSshInputs(sshUser, sshHost);
+async function ensureDevSshConfigBlock(sshUser, sshHost, sshDir, options = {}) {
+  const parsed = parseEnsureSshInputs(sshUser, sshHost, options);
   if ('error' in parsed) {
     return { ok: false, error: parsed.error };
   }
-  const { user, host, hostAlias } = parsed;
-  const dir = ensureSshDir(sshDir);
-  const configPath = path.join(dir, 'config');
-  let existing = '';
-  try {
-    existing = await nodeFsLib.nodeFs().promises.readFile(configPath, 'utf8');
-  } catch (e) {
-    if (e.code !== 'ENOENT') {
-      return { ok: false, error: e.message || String(e) };
-    }
+  const { user, host, hostAlias, legacyHostAlias } = parsed;
+  const configPath = path.join(ensureSshDir(sshDir), 'config');
+  const readResult = await readExistingSshConfig(configPath);
+  if ('error' in readResult) {
+    return { ok: false, error: readResult.error };
+  }
+  const rootDomain = String(options.developerRootDomain || '').trim();
+  const matched = findMatchingHostBlockForUserHost(readResult.content, host, user);
+  const existing = resolveExistingSshBlock(matched, hostAlias, rootDomain);
+  if (existing.skip) {
+    return { ok: true, configPath, hostAlias: existing.hostAlias, skippedDuplicate: true };
   }
-  const matched = findMatchingHostBlockForUserHost(existing, host, user);
-  if (matched) {
-    return {
-      ok: true,
-      configPath,
-      hostAlias: resolveConnectAlias(matched, hostAlias),
-      skippedDuplicate: true
-    };
-  }
-  const next = upsertSshHostBlock(existing, hostAlias, host, user);
-  if (next === existing) {
+  const next = upsertSshHostBlock(readResult.content, hostAlias, host, user);
+  if (next === readResult.content) {
     return { ok: true, configPath, hostAlias };
   }
   await nodeFsLib.nodeFs().promises.writeFile(configPath, next, { mode: 0o600 });
-  return { ok: true, configPath, hostAlias };
+  const migratedFrom = existing.matched
+    ? resolveConnectAlias(existing.matched, hostAlias)
+    : legacyHostAlias;
+  return {
+    ok: true,
+    configPath,
+    hostAlias,
+    updated: true,
+    migratedFrom: migratedFrom !== hostAlias ? migratedFrom : undefined
+  };
 }
 
 module.exports = {
+  formatDeveloperNumericId,
   getDevSshHostAlias,
+  resolveDevSshHostAlias,
   findMatchingHostBlockForUserHost,
+  listHostAliasesForUserHost,
+  removeSshHostBlocksForUserHost,
   resolveConnectAlias,
   upsertSshHostBlock,
   ensureDevSshConfigBlock