@aifabrix/builder 2.49.1 → 2.50.0

package/lib/commands/dev-cli-handlers.js

@@ -16,6 +16,8 @@ const {
   validateDevGroups,
   augmentDevUserGroupsServerError
 } = require('../utils/dev-user-groups');
+const { handleProvisionDevUser, handleRemoveDevUser } = require('./dev-host-ops');
+const { logDevPinShareInstructions } = require('../utils/dev-pin-share-instructions');
 
 const REMOTE_NOT_CONFIGURED_MSG = 'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
 
@@ -26,6 +28,19 @@ const CERT_WIDTH = 10;
 const UNTIL_WIDTH = 22; // 2026-03-20T17:31:14
 const TABLE_SEPARATOR_LENGTH = 130;
 
+/**
+ * Normalize numeric developer id for comparison (e.g. 3 → 03).
+ * @param {string} id - Developer ID
+ * @returns {string}
+ */
+function normalizeDeveloperIdForCompare(id) {
+  const trimmed = String(id ?? '').trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return trimmed;
+  }
+  return String(parseInt(trimmed, 10)).padStart(2, '0');
+}
+
 /**
  * Format certificate validity end for display (e.g. 2026-03-20T17:31:14.000Z -> 2026-03-20T17:31:14).
  * @param {string} iso - ISO 8601 date string
@@ -91,6 +106,10 @@ async function handleDevAdd(options) {
       groups
     }, auth.serverCaPem || undefined);
     logger.log(formatSuccessLine(`Developer ${user.id} created. Use "aifabrix dev pin ${user.id}" to create a PIN for onboarding.`));
+    const noProvision = options.noProvision || options['no-provision'];
+    if (!noProvision) {
+      await handleProvisionDevUser(user.id, options);
+    }
   } catch (err) {
     augmentDevUserGroupsServerError(err, groups);
     throw err;
@@ -131,64 +150,6 @@ async function handleDevUpdate(developerId, options) {
   }
 }
 
-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 — they run one command (the PIN is one-time):')
-  );
-  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('');
-}
-
 /**
  * Handle dev pin – create/regenerate PIN (remote only).
  * @param {string} [developerId] - Developer ID (optional; uses config if omitted)
@@ -222,18 +183,60 @@ async function handleDevPin(developerId, options = {}) {
   });
 }
 
+/**
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+async function promptYesNo(question) {
+  if (!process.stdin.isTTY) {
+    return false;
+  }
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+  });
+}
+
 /**
  * Handle dev delete – remove developer (remote only).
+ * Default: full host removal via host-ops. Use --db-only for API-only delete.
  * @param {string} developerId - Developer ID
+ * @param {Object} [options] - Commander options
  * @returns {Promise<void>}
  */
-async function handleDevDelete(developerId) {
+async function handleDevDelete(developerId, options = {}) {
   const auth = await getRemoteDevAuth();
   if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
   const id = developerId;
   if (!id) throw new Error('Developer ID is required (positional argument or --developer-id).');
-  await devApi.deleteUser(auth.serverUrl, auth.clientCertPem, id, auth.serverCaPem || undefined);
-  logger.log(formatSuccessLine(`Developer ${id} removed.`));
+  const actorId = await config.getDeveloperId();
+  if (
+    actorId &&
+    normalizeDeveloperIdForCompare(actorId) === normalizeDeveloperIdForCompare(id)
+  ) {
+    throw new Error('You cannot delete your own developer account.');
+  }
+  const dbOnly = options.dbOnly || options['db-only'];
+  if (dbOnly) {
+    await devApi.deleteUser(auth.serverUrl, auth.clientCertPem, id, auth.serverCaPem || undefined);
+    logger.log(formatSuccessLine(`Developer ${id} removed from server database.`));
+    return;
+  }
+  const assumeYes = options.yes || options.y;
+  if (!assumeYes) {
+    const ok = await promptYesNo(
+      `Remove developer ${id} from host and server (containers, OS user, database)?`
+    );
+    if (!ok) {
+      logger.log(chalk.gray('Cancelled.'));
+      return;
+    }
+  }
+  await handleRemoveDevUser(id, { ...options, developerId: id });
 }
 
 module.exports = {

package/lib/commands/dev-host-ops-params.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Map Commander options to host-ops job params
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @param {Object} options
+ * @param {string[]} keys
+ * @returns {string|undefined}
+ */
+function firstOption(options, ...keys) {
+  for (const key of keys) {
+    const value = options[key];
+    if (value !== undefined && value !== null && value !== '') {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} options
+ * @param {Array<[string, ...string[]]>} mappings
+ */
+function assignStringParams(params, options, mappings) {
+  for (const [paramKey, ...optionKeys] of mappings) {
+    const value = firstOption(options, ...optionKeys);
+    if (value !== undefined) {
+      params[paramKey] = value;
+    }
+  }
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} options
+ * @param {Array<[string, ...string[]]>} mappings
+ */
+function assignFlagParams(params, options, mappings) {
+  for (const [paramKey, ...optionKeys] of mappings) {
+    if (optionKeys.some((k) => Boolean(options[k]))) {
+      params[paramKey] = true;
+    }
+  }
+}
+
+const STRING_PARAM_MAPPINGS = [
+  ['include', 'include'],
+  ['exclude', 'exclude'],
+  ['builderVersion', 'builderVersion', 'builder-version'],
+  ['adminEmail', 'adminEmail', 'admin-email'],
+  ['adminPassword', 'adminPassword', 'admin-password'],
+  ['platform', 'platform'],
+  ['installation', 'installation']
+];
+
+const FLAG_PARAM_MAPPINGS = [
+  ['skipCert', 'skipCert', 'skip-cert'],
+  ['skipPlatform', 'skipPlatform', 'skip-platform'],
+  ['skipCli', 'skipCli', 'skip-cli'],
+  ['check', 'check'],
+  ['failOnBlocked', 'failOnBlocked']
+];
+
+/**
+ * Build job params from Commander options.
+ * @param {Object} options
+ * @param {string} [developerId]
+ * @returns {Object}
+ */
+function buildJobParams(options, developerId) {
+  const params = {};
+  const id = developerId || firstOption(options, 'developerId', 'developer-id');
+  if (id) {
+    params.developerId = String(id).trim();
+  }
+  assignStringParams(params, options, STRING_PARAM_MAPPINGS);
+  assignFlagParams(params, options, FLAG_PARAM_MAPPINGS);
+  const timeoutMinutes = firstOption(options, 'timeoutMinutes', 'timeout-minutes');
+  if (timeoutMinutes) {
+    params.timeoutMinutes = parseInt(timeoutMinutes, 10);
+  }
+  return params;
+}
+
+module.exports = {
+  buildJobParams,
+  firstOption
+};

package/lib/commands/dev-host-ops-poll.js

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Host-ops job polling loop
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const hostOpsApi = require('../api/host-ops.api');
+const { assertHostOpsJobSucceeded } = require('../utils/host-ops-job-result');
+
+const POLL_INTERVAL_MS = 3000;
+const POLL_TIMEOUT_MS = 3 * 60 * 60 * 1000;
+const TRANSIENT_HTTP_STATUSES = new Set([502, 503, 504]);
+/** Allow ~3 min of consecutive gateway errors (container restart during remove-dev-user). */
+const MAX_TRANSIENT_POLL_ERRORS = 60;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * @param {Error} err
+ * @returns {boolean}
+ */
+function isTransientHostOpsPollError(err) {
+  return Boolean(err && TRANSIENT_HTTP_STATUSES.has(err.status));
+}
+
+/**
+ * @param {Error} err
+ * @param {string} jobId
+ * @returns {Error}
+ */
+function enhanceTransientHostOpsPollError(err, jobId) {
+  const status = err && err.status;
+  const base =
+    status === 502
+      ? 'Builder server returned Bad Gateway while waiting for the host job.'
+      : `Builder server returned HTTP ${status} while waiting for the host job.`;
+  const hint =
+    'The job may still be running on the host (common during platform teardown or container restart). ' +
+    'Wait 1–2 minutes, then run "aifabrix dev list" to verify. ' +
+    `Job id: ${jobId}`;
+  return new Error(`${base} ${hint}`);
+}
+
+/**
+ * @param {Object} auth
+ * @param {string} jobId
+ * @param {Object} pollUi
+ * @returns {Promise<Object>}
+ */
+async function fetchHostOpsJobWithRetry(auth, jobId, pollUi) {
+  const started = Date.now();
+  for (let attempt = 0; attempt <= MAX_TRANSIENT_POLL_ERRORS; attempt += 1) {
+    try {
+      return await hostOpsApi.getHostOpsJob(
+        auth.serverUrl,
+        auth.clientCertPem,
+        jobId,
+        auth.serverCaPem || undefined
+      );
+    } catch (err) {
+      if (!isTransientHostOpsPollError(err)) {
+        throw err;
+      }
+      if (attempt >= MAX_TRANSIENT_POLL_ERRORS) {
+        throw enhanceTransientHostOpsPollError(err, jobId);
+      }
+      if (pollUi && typeof pollUi.onTransientError === 'function') {
+        pollUi.onTransientError(err, Date.now() - started);
+      }
+      await sleep(POLL_INTERVAL_MS);
+    }
+  }
+  throw new Error(`Failed to fetch host-ops job ${jobId} after transient retries`);
+}
+
+/**
+ * @param {Object} auth
+ * @param {string} jobId
+ * @param {Object} pollUi
+ * @param {boolean} json
+ * @returns {Promise<Object>}
+ */
+async function pollHostOpsJobUntilTerminal(auth, jobId, pollUi, json) {
+  const started = Date.now();
+  while (Date.now() - started < POLL_TIMEOUT_MS) {
+    const job = await fetchHostOpsJobWithRetry(auth, jobId, pollUi);
+    if (!json) {
+      pollUi.onPollProgress(job.status);
+    }
+    if (job.status === 'failed') {
+      throw new Error(job.error || `Host-ops job ${jobId} failed`);
+    }
+    if (job.status === 'completed') {
+      assertHostOpsJobSucceeded(job);
+      return job;
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`Timed out waiting for host-ops job ${jobId}`);
+}
+
+module.exports = {
+  POLL_INTERVAL_MS,
+  POLL_TIMEOUT_MS,
+  isTransientHostOpsPollError,
+  enhanceTransientHostOpsPollError,
+  fetchHostOpsJobWithRetry,
+  pollHostOpsJobUntilTerminal
+};

package/lib/commands/dev-host-ops.js

@@ -0,0 +1,252 @@
+/**
+ * @fileoverview Dev host-ops CLI handlers (platform-install, platform-update, etc.)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const readline = require('readline');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { getRemoteDevAuth } = require('../utils/remote-dev-auth');
+const { createHostOpsPollHandlers } = require('../utils/host-ops-poll-ui');
+const { buildHostOpsActionLabel, resolveHostOpsTargetLabel } = require('../utils/host-ops-job-labels');
+const { pollHostOpsJobUntilTerminal } = require('./dev-host-ops-poll');
+const { buildJobParams } = require('./dev-host-ops-params');
+const hostOpsApi = require('../api/host-ops.api');
+const { assertHostOpsJobSucceeded } = require('../utils/host-ops-job-result');
+
+const REMOTE_NOT_CONFIGURED_MSG =
+  'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
+
+/**
+ * @param {string} type
+ * @param {Object} params
+ * @param {Object} options
+ * @returns {Object}
+ */
+function buildHostOpsWaitOpts(type, params, options) {
+  return {
+    wait: options.wait !== false,
+    json: Boolean(options.json),
+    jobType: type,
+    targetLabel: resolveHostOpsTargetLabel(params),
+    params
+  };
+}
+
+/**
+ * Poll host-ops job until terminal state.
+ * @param {Object} auth
+ * @param {string} jobId
+ * @param {Object} [opts]
+ * @param {boolean} [opts.wait=true]
+ * @param {boolean} [opts.json=false]
+ * @returns {Promise<Object>}
+ */
+async function waitForHostOpsJob(auth, jobId, opts = {}) {
+  const wait = opts.wait !== false;
+  const json = Boolean(opts.json);
+  if (!wait) {
+    return { jobId, status: 'pending' };
+  }
+  const pollContext = {
+    jobType: opts.jobType,
+    targetLabel: opts.targetLabel,
+    params: opts.params,
+    startedAt: Date.now()
+  };
+  const pollUi = json
+    ? { onPollProgress: () => {}, onTransientError: () => {}, finish: () => {} }
+    : createHostOpsPollHandlers(jobId, pollContext);
+  try {
+    return await pollHostOpsJobUntilTerminal(auth, jobId, pollUi, json);
+  } finally {
+    pollUi.finish();
+  }
+}
+
+/**
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+function promptYesNo(question) {
+  if (!process.stdin.isTTY) {
+    return Promise.resolve(false);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} [y/N] `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
+    });
+  });
+}
+
+function platformAlreadyInstalled(outcomes) {
+  if (!Array.isArray(outcomes)) return false;
+  return outcomes.some(
+    (row) =>
+      row &&
+      (row.overall === 'SKIP' || row.status === 'SKIP') &&
+      String(row.detail || '').toLowerCase().includes('installed')
+  );
+}
+
+/**
+ * Run a host-ops job and optionally wait.
+ * @param {string} type
+ * @param {Object} params
+ * @param {Object} options - Commander options (yes, wait, json)
+ * @returns {Promise<Object>}
+ */
+async function runHostOpsJob(type, params, options = {}) {
+  const auth = await getRemoteDevAuth();
+  if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+  const { jobId } = await hostOpsApi.createHostOpsJob(
+    auth.serverUrl,
+    auth.clientCertPem,
+    { type, params },
+    auth.serverCaPem || undefined
+  );
+  const waitOpts = buildHostOpsWaitOpts(type, params, options);
+  if (options.wait === false) {
+    if (options.json) {
+      logger.log(JSON.stringify({ jobId, status: 'pending', type }, null, 2));
+    } else {
+      const action = buildHostOpsActionLabel(type, waitOpts.targetLabel);
+      logger.log(formatSuccessLine(`${action} queued (job ${jobId}).`));
+    }
+    return { jobId, status: 'pending' };
+  }
+  if (options.json) {
+    const job = await waitForHostOpsJob(auth, jobId, waitOpts);
+    assertHostOpsJobSucceeded(job);
+    logger.log(JSON.stringify(job, null, 2));
+    return job;
+  }
+  const job = await waitForHostOpsJob(auth, jobId, waitOpts);
+  assertHostOpsJobSucceeded(job);
+  const action = buildHostOpsActionLabel(type, waitOpts.targetLabel);
+  logger.log(formatSuccessLine(`${action} completed.`));
+  return job;
+}
+
+async function handlePlatformInstallCli(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  if (options.check) {
+    params.check = true;
+  } else if (!params.builderVersion) {
+    throw new Error('--builder-version is required unless --check is set');
+  }
+  await runHostOpsJob('install-builder-cli', params, options);
+}
+
+async function handlePlatformUpdate(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  if (options.check) params.check = true;
+  await runHostOpsJob('update-dev-platform', params, options);
+}
+
+function logPlatformInstallOutcomes(developerId, job, json) {
+  if (json) {
+    logger.log(JSON.stringify(job, null, 2));
+    return;
+  }
+  if (!Array.isArray(job.outcomes)) {
+    return;
+  }
+  job.outcomes.forEach((row) => {
+    logger.log(`  ${row.linuxUser || developerId}: ${row.overall || row.status}${row.detail ? ` — ${row.detail}` : ''}`);
+  });
+}
+
+async function runPlatformInstallPreflight(auth, params) {
+  const { jobId } = await hostOpsApi.preflightHostOps(
+    auth.serverUrl,
+    auth.clientCertPem,
+    { type: 'install-dev-platform', params },
+    auth.serverCaPem || undefined
+  );
+  return waitForHostOpsJob(auth, jobId, buildHostOpsWaitOpts('install-dev-platform', params, {}));
+}
+
+async function handlePlatformInstallCheck(developerId, params, options) {
+  const auth = await getRemoteDevAuth();
+  if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+  params.check = true;
+  const { jobId } = await hostOpsApi.preflightHostOps(
+    auth.serverUrl,
+    auth.clientCertPem,
+    { type: 'install-dev-platform', params },
+    auth.serverCaPem || undefined
+  );
+  const job = await waitForHostOpsJob(auth, jobId, buildHostOpsWaitOpts('install-dev-platform', params, options));
+  logPlatformInstallOutcomes(developerId, job, options.json);
+  assertHostOpsJobSucceeded(job);
+  return job;
+}
+
+async function confirmPlatformReinstall(developerId, params, options) {
+  const auth = await getRemoteDevAuth();
+  if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+  const preflight = await runPlatformInstallPreflight(auth, { ...params, developerId });
+  if (!platformAlreadyInstalled(preflight.outcomes)) {
+    return null;
+  }
+  const ok = await promptYesNo(
+    `Platform already installed for dev${String(developerId).padStart(2, '0')}. Re-install?`
+  );
+  if (!ok) {
+    logger.log(chalk.gray('Cancelled.'));
+    return preflight;
+  }
+  await runHostOpsJob('reinstall-dev-platform', params, options);
+  return undefined;
+}
+
+async function handlePlatformInstall(developerId, options) {
+  if (!developerId) {
+    throw new Error('Developer ID is required (positional argument).');
+  }
+  const params = buildJobParams(options, developerId);
+
+  if (options.check) {
+    return handlePlatformInstallCheck(developerId, params, options);
+  }
+
+  if (!options.force && !options.yes) {
+    const cancelled = await confirmPlatformReinstall(developerId, params, options);
+    if (cancelled) {
+      return cancelled;
+    }
+  }
+
+  const jobType = options.force ? 'reinstall-dev-platform' : 'install-dev-platform';
+  await runHostOpsJob(jobType, params, options);
+}
+
+async function handleProvisionDevUser(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  await runHostOpsJob('provision-dev-user', params, options);
+}
+
+async function handleRemoveDevUser(developerId, options) {
+  const params = buildJobParams(options, developerId);
+  if (!params.developerId) {
+    throw new Error('Developer ID is required.');
+  }
+  await runHostOpsJob('remove-dev-user', params, options);
+}
+
+module.exports = {
+  buildJobParams,
+  buildHostOpsWaitOpts,
+  waitForHostOpsJob,
+  runHostOpsJob,
+  handlePlatformInstallCli,
+  handlePlatformUpdate,
+  handlePlatformInstall,
+  handleProvisionDevUser,
+  handleRemoveDevUser
+};

package/lib/commands/dev-init.js

@@ -33,7 +33,7 @@ const {
   isLinuxCaSudoRequiredError
 } = require('../utils/dev-ca-install');
 const { runOptionalHostsSetup } = require('../utils/dev-hosts-helper');
-const { mergeDevSshConfigAfterInit } = require('../utils/dev-init-ssh-merge');
+const { mergeDevSshConfigAfterInit, logDevSshConnectHint } = require('../utils/dev-init-ssh-merge');
 const { resolveInitOptions } = require('../utils/dev-init-resolve');
 const { displayDevConfig } = require('./dev-show-display');
 const {
@@ -426,6 +426,7 @@ async function runCertificateRefresh(auth) {
     warn: (msg) => logger.log(chalk.yellow(`  ⚠ ${msg}`))
   });
   logger.log(formatSuccessLine('Certificate refreshed and config updated from server.\n'));
+  logDevSshConnectHint(await mergeDevSshConfigAfterInit(auth.serverUrl, devId));
 }
 
 /**
@@ -481,6 +482,7 @@ async function runDevRefresh(options = {}) {
     return;
   }
   await fetchAndMergeRemoteSettings(auth, clientCertPem, clientKeyPem, devId);
+  logDevSshConnectHint(await mergeDevSshConfigAfterInit(auth.serverUrl, devId));
 }
 
 module.exports = { runDevInit, runDevRefresh };