@aifabrix/builder 2.42.1 → 2.44.0

package/lib/commands/datasource-validation-cli.js

@@ -0,0 +1,129 @@
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+/**
+ * @fileoverview Shared CLI handling for unified validation (DatasourceTestRun + exit matrix).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { computeExitCodeFromDatasourceTestRun, exitCodeForPollTimeout } = require('../utils/datasource-test-run-exit');
+const { analyzeCapabilityScope } = require('../utils/datasource-test-run-capability-scope');
+const ttyLog = require('../utils/datasource-test-run-tty-log');
+const { logEnvelopeForInteractiveCli } = ttyLog;
+
+/**
+ * Build unified CLI result from integration test return shape.
+ * @param {Object} r - runDatasourceTestIntegration result
+ * @returns {{ envelope: Object|null, apiError: Object|null, pollTimedOut: boolean, incompleteNoAsync: boolean }}
+ */
+function unifiedCliResultFromIntegrationReturn(r) {
+  const meta = r.runMeta || {};
+  return {
+    apiError: meta.apiError || null,
+    pollTimedOut: meta.pollTimedOut === true,
+    incompleteNoAsync: meta.incompleteNoAsync === true,
+    envelope: r.datasourceTestRun || null
+  };
+}
+
+function logApiError(apiError) {
+  logger.error(
+    formatBlockingError('Dataplane request failed:'),
+    apiError.formattedError || apiError.error || 'Request failed'
+  );
+  if (apiError.status) {
+    logger.error(chalk.gray(`  HTTP ${apiError.status}`));
+  }
+}
+
+/**
+ * Print unified validation outcome and return exit code (plan §3.14 watch — no process.exit).
+ * @param {Object} result - From runUnifiedDatasourceValidation
+ * @param {Object} options - CLI flags
+ * @returns {number}
+ */
+function finalizeUnifiedValidationResult(result, options = {}) {
+  if (result.apiError) {
+    logApiError(result.apiError);
+    return 3;
+  }
+  if (result.pollTimedOut) {
+    logger.error(formatBlockingError('Report incomplete: timeout'));
+    return exitCodeForPollTimeout(result.envelope);
+  }
+  if (result.incompleteNoAsync) {
+    logger.error(
+      chalk.red(
+        '✖ Report incomplete: async polling disabled (--no-async) but server returned partial/minimal report.'
+      )
+    );
+    return 3;
+  }
+
+  const envelope = result.envelope;
+  logEnvelopeForInteractiveCli(envelope, options);
+
+  let exitCode = computeExitCodeFromDatasourceTestRun(envelope, {
+    warningsAsErrors: options.warningsAsErrors === true,
+    requireCert: options.requireCert === true
+  });
+  const scope = analyzeCapabilityScope(envelope, options.requestedCapabilityKey);
+  if (options.strictCapabilityScope === true && scope.violated) {
+    exitCode = Math.max(exitCode, 1);
+  }
+  if (
+    exitCode === 2 &&
+    options.requireCert &&
+    !envelope.certificate
+  ) {
+    logger.error(formatBlockingError('Certification not returned; cannot verify.'));
+  }
+  return exitCode;
+}
+
+/**
+ * Handle unified validation result: logs, stdout JSON, process.exit.
+ * @param {Object} result - From runUnifiedDatasourceValidation
+ * @param {Object} options - CLI flags
+ * @returns {void} Exits process
+ */
+function exitFromUnifiedValidationResult(result, options = {}) {
+  process.exit(finalizeUnifiedValidationResult(result, options));
+}
+
+/**
+ * Compute exit code after integration CLI display (no process.exit; plan §3.14 watch).
+ * @param {Object} integrationResult - From runDatasourceTestIntegration
+ * @param {Object} [exitOpts]
+ * @returns {number}
+ */
+function finalizeAfterIntegrationDisplay(integrationResult, exitOpts = {}) {
+  const env = integrationResult.datasourceTestRun;
+  if (!env) {
+    return integrationResult.success ? 0 : 1;
+  }
+  return computeExitCodeFromDatasourceTestRun(env, {
+    warningsAsErrors: exitOpts.warningsAsErrors === true,
+    requireCert: exitOpts.requireCert === true
+  });
+}
+
+/**
+ * Exit after integration CLI when not using raw unified output modes.
+ * @param {Object} integrationResult - From runDatasourceTestIntegration
+ * @param {Object} [exitOpts]
+ */
+function exitAfterIntegrationDisplay(integrationResult, exitOpts = {}) {
+  process.exit(finalizeAfterIntegrationDisplay(integrationResult, exitOpts));
+}
+
+module.exports = {
+  exitFromUnifiedValidationResult,
+  finalizeUnifiedValidationResult,
+  emitReportVersionDiagnostics: ttyLog.emitReportVersionDiagnostics,
+  emitCapabilityScopeDiagnostics: ttyLog.emitCapabilityScopeDiagnostics,
+  unifiedCliResultFromIntegrationReturn,
+  finalizeAfterIntegrationDisplay,
+  exitAfterIntegrationDisplay
+};

package/lib/commands/datasource.js

@@ -1,39 +1,103 @@
 /**
  * AI Fabrix Builder - Datasource Commands
  *
- * Handles datasource validation, listing, comparison, and deployment
- * Commands: datasource validate, datasource list, datasource diff, datasource upload
+ * Handles datasource validation, listing, comparison, deployment, and online validation runs.
+ * Subcommands `test`, `test-integration`, and `test-e2e` call the dataplane unified validation API; permissions are summarized in `docs/commands/permissions.md`.
  *
  * @fileoverview Datasource management commands for AI Fabrix Builder
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
+const path = require('path');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { sectionTitle, headerKeyValue, metadata, formatSuccessLine, formatBlockingError } = require('../utils/cli-test-layout-chalk');
 const { validateDatasourceFile } = require('../datasource/validate');
 const { listDatasources } = require('../datasource/list');
 const { compareDatasources } = require('../datasource/diff');
 const { deployDatasource } = require('../datasource/deploy');
-const { runDatasourceTestIntegration } = require('../datasource/test-integration');
-const { runDatasourceTestE2E } = require('../datasource/test-e2e');
-const { displayIntegrationTestResults, displayE2EResults } = require('../utils/external-system-display');
+const { runLogViewer } = require('../datasource/log-viewer');
+const {
+  setupDatasourceTestCommand,
+  setupDatasourceTestIntegrationCommand,
+  setupDatasourceTestE2ECommand
+} = require('./datasource-unified-test-cli');
+
+const DATASOURCE_HELP_AFTER = `
+Subcommands:
+  validate <file-or-key>       Validate datasource JSON (path or datasource key under integration/<app>/)
+  list                         List datasources (env from config)
+  upload <file-or-key>         Deploy one datasource JSON to the dataplane (path or key; systemKey in file)
+  diff                         Compare two datasource JSON files
+  test <key>                   Structural/policy validation via unified dataplane API (DatasourceTestRun)
+  test-integration / test-e2e  Integration or E2E run via the same unified validation API
+  log-integration / log-e2e    Show saved test logs
+`;
+
+const DATASOURCE_VALIDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix datasource validate test-e2e-hubspot-users
+  $ aifabrix datasource validate integration/myapp/myapp-datasource-contacts.json
+  $ aifabrix datasource validate ./test-e2e-hubspot-datasource-users.json
+  $ aifabrix datasource validate /path/to/system-datasource-entity.json
+  $ af ds validate ../integration/hubspot/hubspot-datasource-deals.json
+`;
+
+const DATASOURCE_UPLOAD_HELP_AFTER = `
+Examples:
+  $ aifabrix datasource upload test-e2e-hubspot-users
+  $ aifabrix datasource upload integration/myapp/myapp-datasource-contacts.json
+  $ aifabrix datasource upload ./test-e2e-hubspot-datasource-users.json
+  $ aifabrix datasource upload /path/to/system-datasource-entity.json
+  $ af ds upload ../integration/hubspot/hubspot-datasource-deals.json
+`;
+
+/**
+ * TTY layout for local datasource JSON validation (aligned with cli-test-layout-chalk).
+ * @param {{ valid: boolean, errors: string[], resolvedPath: string }} result
+ * @param {string} trimmed - original CLI argument
+ * @param {boolean} showMapping - show Key + File when key resolved to a path
+ */
+function logDatasourceValidateOutcome(result, trimmed, showMapping) {
+  logger.log('');
+  logger.log(sectionTitle('Datasource validation'));
+  logger.log(metadata('Offline — JSON schema and integration wiring'));
+  logger.log('');
+  if (!result.valid) {
+    logger.log(headerKeyValue('File:', result.resolvedPath));
+    logger.log('');
+    logger.log(formatBlockingError('Datasource file has errors:'));
+    result.errors.forEach(error => logger.log(chalk.red(`  • ${error}`)));
+    return;
+  }
+  if (showMapping) {
+    logger.log(headerKeyValue('Key:', trimmed));
+    logger.log(headerKeyValue('File:', result.resolvedPath));
+  } else {
+    logger.log(headerKeyValue('File:', result.resolvedPath));
+  }
+  logger.log('');
+  logger.log(formatSuccessLine('Datasource file is valid.'));
+}
 
 function setupDatasourceValidateCommand(datasource) {
-  datasource.command('validate <file>')
-    .description('Validate external datasource JSON file')
-    .action(async(file) => {
+  datasource.command('validate <file-or-key>')
+    .description('Validate datasource JSON (file path or datasource key under integration/<app>/)')
+    .addHelpText('after', DATASOURCE_VALIDATE_HELP_AFTER)
+    .action(async(fileOrKey) => {
       try {
-        const result = await validateDatasourceFile(file);
-        if (result.valid) {
-          logger.log(chalk.green(`\n✓ Datasource file is valid: ${file}`));
-        } else {
-          logger.log(chalk.red(`\n✗ Datasource file has errors: ${file}`));
-          result.errors.forEach(error => logger.log(chalk.red(`  • ${error}`)));
+        const trimmed = fileOrKey.trim();
+        const result = await validateDatasourceFile(trimmed);
+        const resolvedPath = result.resolvedPath;
+        const argResolved = path.resolve(trimmed);
+        const showMapping = resolvedPath && argResolved !== resolvedPath && trimmed !== resolvedPath;
+        logDatasourceValidateOutcome(result, trimmed, showMapping);
+        if (!result.valid) {
           process.exit(1);
         }
       } catch (error) {
-        logger.error(chalk.red('❌ Validation failed:'), error.message);
+        logger.error(formatBlockingError('Validation failed:'), error.message);
         process.exit(1);
       }
     });
@@ -41,12 +105,12 @@ function setupDatasourceValidateCommand(datasource) {
 
 function setupDatasourceListCommand(datasource) {
   datasource.command('list')
-    .description('List datasources from environment (uses environment from config.yaml)')
+    .description('List datasources for environment in config')
     .action(async() => {
       try {
         await listDatasources({});
       } catch (error) {
-        logger.error(chalk.red('❌ Failed to list datasources:'), error.message);
+        logger.error(formatBlockingError('Failed to list datasources:'), error.message);
         process.exit(1);
       }
     });
@@ -54,91 +118,70 @@ function setupDatasourceListCommand(datasource) {
 
 function setupDatasourceDiffCommand(datasource) {
   datasource.command('diff <file1> <file2>')
-    .description('Compare two datasource configuration files (for dataplane)')
+    .description('Diff two datasource JSON files')
     .action(async(file1, file2) => {
       try {
         await compareDatasources(file1, file2);
       } catch (error) {
-        logger.error(chalk.red('❌ Diff failed:'), error.message);
+        logger.error(formatBlockingError('Diff failed:'), error.message);
         process.exit(1);
       }
     });
 }
 
 function setupDatasourceUploadCommand(datasource) {
-  datasource.command('upload <myapp> <file>')
-    .description('Upload datasource to dataplane')
-    .action(async(myapp, file, options) => {
+  datasource.command('upload <file-or-key>')
+    .description('Deploy datasource JSON to dataplane (file path or datasource key under integration/<app>/)')
+    .addHelpText('after', DATASOURCE_UPLOAD_HELP_AFTER)
+    .action(async(fileOrKey, options) => {
       try {
-        await deployDatasource(myapp, file, options);
+        await deployDatasource(fileOrKey, options);
       } catch (error) {
-        logger.error(chalk.red('❌ Upload failed:'), error.message);
+        logger.error(formatBlockingError('Upload failed:'), error.message);
         process.exit(1);
       }
     });
 }
 
-function setupDatasourceTestIntegrationCommand(datasource) {
-  datasource.command('test-integration <datasourceKey>')
-    .description('Run integration (config) test for one datasource via dataplane pipeline')
-    .option('-a, --app <appKey>', 'App key (default: resolve from cwd if inside integration/<appKey>/)')
-    .option('-p, --payload <file>', 'Path to custom test payload file')
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro')
-    .option('--debug', 'Include debug output and write log to integration/<appKey>/logs/')
-    .option('--timeout <ms>', 'Request timeout in milliseconds', '30000')
+function setupDatasourceLogE2ECommand(datasource) {
+  datasource.command('log-e2e <datasourceKey>')
+    .description('Show E2E test log (latest or --file)')
+    .option(
+      '-a, --app <app>',
+      'Integration folder name (optional: resolve from cwd or datasource key if single match)'
+    )
+    .option('-f, --file <path>', 'Path to log file (default: latest in app logs folder)')
     .action(async(datasourceKey, options) => {
       try {
-        const result = await runDatasourceTestIntegration(datasourceKey, {
+        await runLogViewer(datasourceKey, {
           app: options.app,
-          payload: options.payload,
-          environment: options.env,
-          debug: options.debug,
-          timeout: options.timeout
+          file: options.file,
+          logType: 'test-e2e'
         });
-        displayIntegrationTestResults({
-          systemKey: result.systemKey || 'unknown',
-          datasourceResults: [result],
-          success: result.success
-        }, options.verbose);
-        if (!result.success) process.exit(1);
       } catch (error) {
-        logger.error(chalk.red('❌ Integration test failed:'), error.message);
+        logger.error(formatBlockingError('log-e2e failed:'), error.message);
         process.exit(1);
       }
     });
 }
 
-function setupDatasourceTestE2ECommand(datasource) {
-  datasource.command('test-e2e <datasourceKey>')
-    .description('Run E2E test for one datasource (config, credential, sync, data, CIP) via dataplane')
-    .option('-a, --app <appKey>', 'App key (default: resolve from cwd if inside integration/<appKey>/)')
-    .option('-e, --env <env>', 'Environment: dev, tst, or pro')
-    .option('-v, --verbose', 'Show detailed step output and poll progress')
-    .option('--debug', 'Include debug output and write log to integration/<appKey>/logs/')
-    .option('--test-crud', 'Enable CRUD lifecycle test (body testCrud: true)')
-    .option('--record-id <id>', 'Record ID for test (body recordId)')
-    .option('--no-cleanup', 'Disable cleanup after test (body cleanup: false)')
-    .option('--primary-key-value <value|@path>', 'Primary key value or path to JSON file (e.g. @pk.json) for body primaryKeyValue')
-    .option('--no-async', 'Use sync mode (no polling); single POST, no asyncRun')
+function setupDatasourceLogIntegrationCommand(datasource) {
+  datasource.command('log-integration <datasourceKey>')
+    .description('Show integration test log (latest or --file)')
+    .option(
+      '-a, --app <app>',
+      'Integration folder name (optional: resolve from cwd or datasource key if single match)'
+    )
+    .option('-f, --file <path>', 'Path to log file (default: latest in app logs folder)')
     .action(async(datasourceKey, options) => {
       try {
-        const data = await runDatasourceTestE2E(datasourceKey, {
+        await runLogViewer(datasourceKey, {
           app: options.app,
-          environment: options.env,
-          debug: options.debug,
-          verbose: options.verbose,
-          async: options.async !== false,
-          testCrud: options.testCrud,
-          recordId: options.recordId,
-          cleanup: options.cleanup,
-          primaryKeyValue: options.primaryKeyValue
+          file: options.file,
+          logType: 'test-integration'
         });
-        displayE2EResults(data, options.verbose);
-        const steps = data.steps || data.completedActions || [];
-        const failed = data.success === false || steps.some(s => s.success === false || s.error);
-        if (failed) process.exit(1);
       } catch (error) {
-        logger.error(chalk.red('❌ E2E test failed:'), error.message);
+        logger.error(formatBlockingError('log-integration failed:'), error.message);
         process.exit(1);
       }
     });
@@ -149,13 +192,22 @@ function setupDatasourceTestE2ECommand(datasource) {
  * @param {Command} program - Commander program instance
  */
 function setupDatasourceCommands(program) {
-  const datasource = program.command('datasource').description('Manage external data sources');
+  const datasource = program
+    .command('datasource')
+    .description('Datasource JSON: validate, list, deploy, test, logs')
+    .addHelpText('after', DATASOURCE_HELP_AFTER);
+  if (typeof datasource.alias === 'function') {
+    datasource.alias('ds');
+  }
   setupDatasourceValidateCommand(datasource);
   setupDatasourceListCommand(datasource);
   setupDatasourceDiffCommand(datasource);
   setupDatasourceUploadCommand(datasource);
+  setupDatasourceTestCommand(datasource);
   setupDatasourceTestIntegrationCommand(datasource);
   setupDatasourceTestE2ECommand(datasource);
+  setupDatasourceLogE2ECommand(datasource);
+  setupDatasourceLogIntegrationCommand(datasource);
 }
 
 module.exports = { setupDatasourceCommands };

package/lib/commands/deployment-list.js

@@ -1,3 +1,4 @@
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
 /**
  * Deployment list commands – list deployments for environment or for an app
  * Uses GET .../deployments and GET .../applications/{appKey}/deployments.
@@ -97,7 +98,7 @@ async function runDeploymentList(options = {}) {
     );
     displayDeploymentList(extractDeployments(response), environment, authResult.controllerUrl);
   } catch (error) {
-    logger.error(chalk.red(`❌ Failed to list deployments: ${error.message}`));
+    logger.error(formatBlockingError(`Failed to list deployments: ${error.message}`));
     process.exit(1);
   }
 }
@@ -133,13 +134,13 @@ function displayAppDeploymentList(deployments, appKey, environment, controllerUr
 async function resolveDeploymentListContext(options) {
   const controllerUrl = options.controller || (await resolveControllerUrl());
   if (!controllerUrl) {
-    logger.error(chalk.red('❌ Controller URL is required. Run "aifabrix login" first.'));
+    logger.error(formatBlockingError('Controller URL is required. Run "aifabrix login" first.'));
     process.exit(1);
   }
   const environment = options.environment || (await resolveEnvironment());
   const authResult = await getDeploymentListAuth(controllerUrl);
   if (!authResult || !authResult.token) {
-    logger.error(chalk.red(`❌ No authentication token for controller: ${controllerUrl}`));
+    logger.error(formatBlockingError(`No authentication token for controller: ${controllerUrl}`));
     logger.error(chalk.gray('Run: aifabrix login'));
     process.exit(1);
   }
@@ -158,7 +159,7 @@ async function resolveDeploymentListContext(options) {
  */
 async function runAppDeploymentList(appKey, options = {}) {
   if (!appKey || typeof appKey !== 'string') {
-    logger.error(chalk.red('❌ Application key is required.'));
+    logger.error(formatBlockingError('Application key is required.'));
     process.exit(1);
     return;
   }
@@ -180,7 +181,7 @@ async function runAppDeploymentList(appKey, options = {}) {
       authResult.controllerUrl
     );
   } catch (error) {
-    logger.error(chalk.red(`❌ Failed to list deployments for ${appKey}: ${error.message}`));
+    logger.error(formatBlockingError(`Failed to list deployments for ${appKey}: ${error.message}`));
     process.exit(1);
   }
 }

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

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * @fileoverview CLI action handlers for dev list/add/update/pin/delete (remote Builder Server)
  * @author AI Fabrix Team
@@ -9,6 +10,12 @@ const config = require('../core/config');
 const logger = require('../utils/logger');
 const devApi = require('../api/dev.api');
 const { getRemoteDevAuth } = require('../utils/remote-dev-auth');
+const { isValidIpv4 } = require('../utils/dev-hosts-helper');
+const {
+  parseDevGroupsOption,
+  validateDevGroups,
+  augmentDevUserGroupsServerError
+} = require('../utils/dev-user-groups');
 
 const REMOTE_NOT_CONFIGURED_MSG = 'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
 
@@ -39,7 +46,7 @@ async function handleDevList() {
     logger.log(chalk.yellow(REMOTE_NOT_CONFIGURED_MSG));
     return;
   }
-  const users = await devApi.listUsers(auth.serverUrl, auth.clientCertPem);
+  const users = await devApi.listUsers(auth.serverUrl, auth.clientCertPem, auth.serverCaPem || undefined);
   if (users.length === 0) {
     logger.log(chalk.gray('No developers registered.'));
     return;
@@ -71,14 +78,23 @@ async function handleDevList() {
 async function handleDevAdd(options) {
   const auth = await getRemoteDevAuth();
   if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
-  const groups = (options.groups || 'developer').split(',').map(s => s.trim()).filter(Boolean);
-  const user = await devApi.createUser(auth.serverUrl, auth.clientCertPem, {
-    developerId: options.developerId,
-    name: options.name,
-    email: options.email,
-    groups: groups.length ? groups : ['developer']
-  });
-  logger.log(chalk.green(`✓ Developer ${user.id} created. Use "aifabrix dev pin ${user.id}" to create a PIN for onboarding.`));
+  let groups = parseDevGroupsOption(
+    options.groups !== undefined && options.groups !== null ? options.groups : 'developer'
+  );
+  if (groups.length === 0) groups = ['developer'];
+  validateDevGroups(groups);
+  try {
+    const user = await devApi.createUser(auth.serverUrl, auth.clientCertPem, {
+      developerId: options.developerId,
+      name: options.name,
+      email: options.email,
+      groups
+    }, auth.serverCaPem || undefined);
+    logger.log(formatSuccessLine(`Developer ${user.id} created. Use "aifabrix dev pin ${user.id}" to create a PIN for onboarding.`));
+  } catch (err) {
+    augmentDevUserGroupsServerError(err, groups);
+    throw err;
+  }
 }
 
 /**
@@ -95,27 +111,115 @@ async function handleDevUpdate(developerId, options) {
   const body = {};
   if (options.name) body.name = options.name;
   if (options.email) body.email = options.email;
-  if (options.groups) body.groups = options.groups.split(',').map(s => s.trim()).filter(Boolean);
+  if (options.groups) {
+    const groups = parseDevGroupsOption(options.groups);
+    if (groups.length === 0) {
+      throw new Error('--groups must list at least one valid group');
+    }
+    validateDevGroups(groups);
+    body.groups = groups;
+  }
   if (Object.keys(body).length === 0) {
     throw new Error('Provide at least one of --name, --email, --groups');
   }
-  await devApi.updateUser(auth.serverUrl, auth.clientCertPem, id, body);
-  logger.log(chalk.green(`✓ Developer ${id} updated.`));
+  try {
+    await devApi.updateUser(auth.serverUrl, auth.clientCertPem, id, body, auth.serverCaPem || undefined);
+    logger.log(formatSuccessLine(`Developer ${id} updated.`));
+  } catch (err) {
+    augmentDevUserGroupsServerError(err, body.groups);
+    throw err;
+  }
+}
+
+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)
+ * @param {Object} [options] - Commander options
+ * @param {string} [options.hostsIp] - From --hosts-ip (embeds IPv4 in the hosts variant)
  * @returns {Promise<void>}
  */
-async function handleDevPin(developerId) {
+async function handleDevPin(developerId, options = {}) {
   const auth = await getRemoteDevAuth();
   if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
   const id = developerId || await config.getDeveloperId();
   if (!id) throw new Error('developerId is required (argument or set developer-id in config)');
-  const res = await devApi.createPin(auth.serverUrl, auth.clientCertPem, id);
-  logger.log(chalk.green(`✓ PIN created for ${id}, expires ${res.expiresAt}.`));
-  logger.log(chalk.yellow(`  Give this PIN once to the developer for: aifabrix dev init --developer-id ${id} --server ${auth.serverUrl} --pin ${res.pin}`));
+  const rawHostsIp = options.hostsIp ?? options['hosts-ip'];
+  let hostsIp = '';
+  if (rawHostsIp !== undefined && rawHostsIp !== null) {
+    const trimmed = String(rawHostsIp).trim();
+    if (trimmed !== '') {
+      if (!isValidIpv4(trimmed)) {
+        throw new Error('Invalid --hosts-ip (use an IPv4 address, e.g. 192.168.1.25)');
+      }
+      hostsIp = trimmed;
+    }
+  }
+  const res = await devApi.createPin(auth.serverUrl, auth.clientCertPem, id, auth.serverCaPem || undefined);
+  logDevPinShareInstructions({
+    id,
+    serverUrl: auth.serverUrl,
+    pin: res.pin,
+    expiresAt: res.expiresAt,
+    hostsIp: hostsIp || undefined
+  });
 }
 
 /**
@@ -128,8 +232,8 @@ async function handleDevDelete(developerId) {
   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);
-  logger.log(chalk.green(`✓ Developer ${id} removed.`));
+  await devApi.deleteUser(auth.serverUrl, auth.clientCertPem, id, auth.serverCaPem || undefined);
+  logger.log(formatSuccessLine(`Developer ${id} removed.`));
 }
 
 module.exports = {