@aifabrix/builder 2.40.2 → 2.41.0

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

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview CLI action handlers for dev list/add/update/pin/delete (remote Builder Server)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const config = require('../core/config');
+const logger = require('../utils/logger');
+const devApi = require('../api/dev.api');
+const { getRemoteDevAuth } = require('../utils/remote-dev-auth');
+
+const REMOTE_NOT_CONFIGURED_MSG = 'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
+
+const ID_WIDTH = 8;
+const NAME_WIDTH = 25;
+const EMAIL_WIDTH = 30;
+const CERT_WIDTH = 10;
+const UNTIL_WIDTH = 22; // 2026-03-20T17:31:14
+const TABLE_SEPARATOR_LENGTH = 130;
+
+/**
+ * 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
+ * @returns {string} Truncated datetime without milliseconds and Z
+ */
+function formatCertUntil(iso) {
+  if (!iso || typeof iso !== 'string') return '?';
+  return iso.replace(/\.\d{3}Z?$/i, '').trim();
+}
+
+/**
+ * Handle dev list – list developer users (remote only). Table format, sorted by name.
+ * @returns {Promise<void>}
+ */
+async function handleDevList() {
+  const auth = await getRemoteDevAuth();
+  if (!auth) {
+    logger.log(chalk.yellow(REMOTE_NOT_CONFIGURED_MSG));
+    return;
+  }
+  const users = await devApi.listUsers(auth.serverUrl, auth.clientCertPem);
+  if (users.length === 0) {
+    logger.log(chalk.gray('No developers registered.'));
+    return;
+  }
+  logger.log(chalk.bold('\n📋 Developers:\n'));
+  logger.log(chalk.gray('ID'.padEnd(ID_WIDTH) + 'Name'.padEnd(NAME_WIDTH) + 'Email'.padEnd(EMAIL_WIDTH) + 'Cert'.padEnd(CERT_WIDTH) + 'Until'.padEnd(UNTIL_WIDTH) + 'Groups'));
+  logger.log(chalk.gray('-'.repeat(TABLE_SEPARATOR_LENGTH)));
+  const sorted = [...users].sort((a, b) => (a.name || '').localeCompare(b.name || '', undefined, { sensitivity: 'base' }));
+  sorted.forEach(u => {
+    const certLabel = u.certificateIssued ? 'yes' : 'no cert';
+    const untilRaw = u.certificateIssued && u.certificateValidNotAfter ? u.certificateValidNotAfter : null;
+    const untilStr = untilRaw ? formatCertUntil(untilRaw) : '-';
+    const id = String(u.id ?? '').padEnd(ID_WIDTH);
+    const name = (u.name || 'N/A').padEnd(NAME_WIDTH);
+    const email = (u.email || 'N/A').padEnd(EMAIL_WIDTH);
+    const cert = certLabel.padEnd(CERT_WIDTH);
+    const until = untilStr.padEnd(UNTIL_WIDTH);
+    const groups = (u.groups || []).join(', ');
+    logger.log(`${id}${name}${email}${cert}${until}${groups}`);
+  });
+  logger.log('');
+}
+
+/**
+ * Handle dev add – create developer (remote only).
+ * @param {Object} options - Commander options (developerId, name, email, groups)
+ * @returns {Promise<void>}
+ */
+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.`));
+}
+
+/**
+ * Handle dev update – update developer (remote only).
+ * @param {string} developerId - Developer ID
+ * @param {Object} options - Commander options (name, email, groups)
+ * @returns {Promise<void>}
+ */
+async function handleDevUpdate(developerId, options) {
+  const auth = await getRemoteDevAuth();
+  if (!auth) throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+  const id = options.developerId || options['developer-id'] || developerId;
+  if (!id) throw new Error('Developer ID is required (--developer-id or positional argument).');
+  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 (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.`));
+}
+
+/**
+ * Handle dev pin – create/regenerate PIN (remote only).
+ * @param {string} [developerId] - Developer ID (optional; uses config if omitted)
+ * @returns {Promise<void>}
+ */
+async function handleDevPin(developerId) {
+  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}`));
+}
+
+/**
+ * Handle dev delete – remove developer (remote only).
+ * @param {string} developerId - Developer ID
+ * @returns {Promise<void>}
+ */
+async function handleDevDelete(developerId) {
+  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);
+  logger.log(chalk.green(`✓ Developer ${id} removed.`));
+}
+
+module.exports = {
+  handleDevList,
+  handleDevAdd,
+  handleDevUpdate,
+  handleDevPin,
+  handleDevDelete
+};

package/lib/commands/dev-down.js

@@ -0,0 +1,114 @@
+/**
+ * dev down – stop Mutagen sync sessions and optionally app containers for this developer.
+ *
+ * @fileoverview Dev down command (plan 65: stop sync sessions; optional stop apps)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const appLib = require('../app');
+
+const execAsync = promisify(exec);
+
+/**
+ * Stop Mutagen sync sessions for this developer (session names aifabrix-<dev-id>-*).
+ * When Mutagen is not available or no sessions exist, no-op.
+ * @param {string} developerId - Developer ID
+ * @returns {Promise<void>}
+ */
+async function stopMutagenSessions(developerId) {
+  const { getMutagenPath } = require('../utils/mutagen');
+  const mutagenPath = await getMutagenPath();
+  if (!mutagenPath) {
+    logger.log(chalk.gray('Mutagen not installed; no sync sessions to stop.'));
+    return;
+  }
+  try {
+    const { stdout } = await execAsync(`"${mutagenPath}" sync list --template '{{.Name}}'`, {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+    const sessions = (stdout || '').trim().split('\n').filter(Boolean);
+    const prefix = `aifabrix-${developerId}-`;
+    const toTerminate = sessions.filter(name => name.startsWith(prefix));
+    for (const name of toTerminate) {
+      await execAsync(`"${mutagenPath}" sync terminate "${name}"`, { timeout: 5000 });
+      logger.log(chalk.green(`  ✓ Stopped sync session: ${name}`));
+    }
+    if (toTerminate.length === 0 && sessions.length > 0) {
+      logger.log(chalk.gray('No sync sessions for this developer.'));
+    } else if (toTerminate.length === 0) {
+      logger.log(chalk.gray('No Mutagen sync sessions to stop.'));
+    }
+  } catch (err) {
+    logger.log(chalk.gray('No Mutagen sync sessions to stop.'));
+  }
+}
+
+const INFRA_SUFFIXES = ['-postgres', '-redis', '-pgadmin', '-redis-commander', '-traefik', '-db-init'];
+
+/**
+ * List running app container names for this developer (excludes infra containers).
+ * @param {string} developerId - Developer ID
+ * @returns {Promise<string[]>} Container names (e.g. aifabrix-dev1-myapp)
+ */
+async function listAppContainersForDeveloper(developerId) {
+  const idNum = parseInt(developerId, 10);
+  const filter = idNum === 0 ? 'aifabrix-' : `aifabrix-dev${developerId}-`;
+  const { stdout } = await execAsync(
+    `docker ps --filter "name=${filter}" --format "{{.Names}}"`,
+    { encoding: 'utf8' }
+  );
+  const names = (stdout || '').trim().split('\n').filter(Boolean);
+  return names.filter(n => !INFRA_SUFFIXES.some(s => n.endsWith(s)));
+}
+
+/**
+ * Extract app name from container name (aifabrix-dev1-myapp -> myapp, aifabrix-myapp -> myapp).
+ * @param {string} containerName - Container name
+ * @param {string} developerId - Developer ID
+ * @returns {string} App name
+ */
+function appNameFromContainer(containerName, developerId) {
+  const idNum = parseInt(developerId, 10);
+  const prefix = idNum === 0 ? 'aifabrix-' : `aifabrix-dev${developerId}-`;
+  return containerName.startsWith(prefix) ? containerName.slice(prefix.length) : containerName;
+}
+
+/**
+ * Handle dev down: stop Mutagen sessions; optionally stop app containers.
+ * @param {Object} options - { apps: boolean }
+ * @returns {Promise<void>}
+ */
+async function handleDevDown(options = {}) {
+  const developerId = await config.getDeveloperId();
+  logger.log(chalk.blue('\nStopping dev resources for developer ' + developerId + '...\n'));
+
+  await stopMutagenSessions(developerId);
+
+  if (options.apps) {
+    const containers = await listAppContainersForDeveloper(developerId);
+    for (const containerName of containers) {
+      const appName = appNameFromContainer(containerName, developerId);
+      if (!appName) continue;
+      try {
+        await appLib.downApp(appName, {});
+        logger.log(chalk.green(`  ✓ Stopped app: ${appName}`));
+      } catch (err) {
+        logger.log(chalk.yellow(`  ⚠ Could not stop ${appName}: ${err.message}`));
+      }
+    }
+    if (containers.length === 0) {
+      logger.log(chalk.gray('No running app containers for this developer.'));
+    }
+  }
+
+  logger.log(chalk.green('\n✓ dev down complete.\n'));
+}
+
+module.exports = { handleDevDown };

package/lib/commands/dev-init.js

@@ -0,0 +1,309 @@
+/**
+ * @fileoverview aifabrix dev init – onboard with Builder Server (issue-cert, save cert, get settings, add SSH key).
+ * Auth: first call (issue-cert) uses no client cert; all other calls (getSettings, addSshKey, and every other dev API) send the client certificate.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+const config = require('../core/config');
+const { getConfigDirForPaths } = require('../utils/paths');
+const { generateCSR, getCertDir, readClientCertPem, readClientKeyPem, getCertValidNotAfter } = require('../utils/dev-cert-helper');
+const { getOrCreatePublicKeyContent } = require('../utils/ssh-key-helper');
+const devApi = require('../api/dev.api');
+const logger = require('../utils/logger');
+
+/**
+ * Validate init options and return normalized baseUrl and devId.
+ * @param {Object} options - Commander options
+ * @returns {{ baseUrl: string, devId: string }}
+ */
+function validateInitOptions(options) {
+  const devId = options.developerId || options['developer-id'];
+  const server = options.server;
+  const pin = options.pin;
+
+  if (!devId || typeof devId !== 'string' || !/^[0-9]+$/.test(devId)) {
+    throw new Error('--developer-id is required and must be a non-empty digit string (e.g. 01)');
+  }
+  if (!server || typeof server !== 'string' || !server.trim()) {
+    throw new Error('--server is required and must be the Builder Server base URL (e.g. https://dev.aifabrix.dev)');
+  }
+  if (!pin || typeof pin !== 'string' || !pin.trim()) {
+    throw new Error('--pin is required (one-time PIN from your admin)');
+  }
+  return { baseUrl: server.trim().replace(/\/+$/, ''), devId };
+}
+
+/**
+ * Request certificate from Builder Server; map API errors to user messages.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} devId - Developer ID
+ * @param {string} pin - One-time PIN
+ * @param {string} csrPem - PEM CSR
+ * @returns {Promise<Object>} IssueCertResponseDto
+ */
+async function requestCertificate(baseUrl, devId, pin, csrPem) {
+  try {
+    return await devApi.issueCert(baseUrl, {
+      developerId: devId,
+      pin: pin.trim(),
+      csr: csrPem
+    });
+  } catch (err) {
+    if (err.status === 401) {
+      throw new Error('Invalid or expired PIN. Ask your admin for a new PIN (aifabrix dev pin <developerId>).');
+    }
+    if (err.status === 404) {
+      throw new Error(`Developer ${devId} not found on the server.`);
+    }
+    if (err.status === 503) {
+      throw new Error('Certificate signing is temporarily unavailable. Try again later.');
+    }
+    throw err;
+  }
+}
+
+/**
+ * Normalize PEM string: turn literal \n (backslash-n) into real newlines so Docker/OpenSSL accept it.
+ * Some servers return JSON with escaped newlines in the PEM string.
+ * @param {string} pem - PEM string (certificate or CA)
+ * @returns {string} PEM with real newlines
+ */
+function normalizePemNewlines(pem) {
+  if (typeof pem !== 'string') return pem;
+  return pem.replace(/\\n/g, '\n');
+}
+
+/**
+ * Save certificate, key, and optional CA to cert dir; set developer-id in config.
+ * Remote Docker requires ca.pem in the cert dir; if the server provides it (e.g. issue-cert
+ * response caCertificate or ca), it is saved so DOCKER_CERT_PATH works.
+ * @param {string} configDir - Config directory
+ * @param {string} devId - Developer ID
+ * @param {string} certificatePem - Issued certificate PEM
+ * @param {string} keyPem - Private key PEM
+ * @param {string} [caPem] - Optional CA certificate PEM (for remote Docker TLS)
+ */
+async function saveCertAndConfig(configDir, devId, certificatePem, keyPem, caPem) {
+  const certDir = getCertDir(configDir, devId);
+  await fs.mkdir(certDir, { recursive: true });
+  const certNormalized = normalizePemNewlines(certificatePem);
+  const keyNormalized = normalizePemNewlines(keyPem);
+  await fs.writeFile(path.join(certDir, 'cert.pem'), certNormalized, { mode: 0o600 });
+  await fs.writeFile(path.join(certDir, 'key.pem'), keyNormalized, { mode: 0o600 });
+  if (caPem && typeof caPem === 'string' && caPem.trim()) {
+    const caNormalized = normalizePemNewlines(caPem.trim());
+    await fs.writeFile(path.join(certDir, 'ca.pem'), caNormalized, { mode: 0o600 });
+    logger.log(chalk.green('  ✓ Certificate and CA saved to ') + chalk.cyan(path.join(certDir, 'cert.pem')));
+  } else {
+    logger.log(chalk.green('  ✓ Certificate saved to ') + chalk.cyan(path.join(certDir, 'cert.pem')));
+  }
+  await config.setDeveloperId(devId);
+  logger.log(chalk.green('  ✓ Developer ID set to ') + chalk.cyan(devId));
+}
+
+/**
+ * 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.'));
+}
+
+/**
+ * Register SSH public key with Builder Server for Mutagen sync.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} clientCertPem - Client certificate PEM
+ * @param {string} clientKeyPem - Client private key PEM (for mTLS)
+ * @param {string} devId - Developer ID
+ */
+async function registerSshKey(baseUrl, clientCertPem, clientKeyPem, devId) {
+  const publicKey = getOrCreatePublicKeyContent();
+  try {
+    await devApi.addSshKey(baseUrl, clientCertPem, devId, {
+      publicKey,
+      label: 'aifabrix-init'
+    }, clientKeyPem);
+    logger.log(chalk.green('  ✓ SSH key registered'));
+  } catch (err) {
+    if (err.status === 409) {
+      logger.log(chalk.yellow('  ⚠ SSH key already registered'));
+    } else {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Run SSH key registration step (log, register, handle 400 hint).
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {Object} issueResponse - IssueCert response (certificate)
+ * @param {string} keyPem - Client key PEM
+ * @param {string} configDir - Config directory
+ * @param {string} devId - Developer ID
+ * @private
+ */
+async function _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId) {
+  logger.log(chalk.gray('  Registering SSH key for Mutagen sync...'));
+  try {
+    if (keyPem && typeof keyPem === 'string') {
+      logger.log(chalk.gray('  Using client certificate for TLS'));
+    }
+    await registerSshKey(baseUrl, issueResponse.certificate, keyPem, devId);
+  } catch (err) {
+    const msg = err.status === 400 ? getBadRequestHint() : (err.message || String(err));
+    logger.log(chalk.yellow('  ⚠ Could not register SSH key: ' + msg));
+    logCertTroubleshootingHint(configDir, devId, baseUrl);
+  }
+}
+
+/**
+ * Apply settings from issue-cert response or fetch via getSettings; merge into config.
+ * @param {string} baseUrl - Builder Server base URL
+ * @param {string} devId - Developer ID
+ * @param {Object} issueResponse - IssueCert response (certificate, settings)
+ * @param {string} keyPem - Client key PEM
+ */
+async function applySettingsFromServer(baseUrl, devId, issueResponse, keyPem) {
+  const configDir = getConfigDirForPaths();
+  if (issueResponse.settings && typeof issueResponse.settings === 'object') {
+    await config.mergeRemoteSettings(issueResponse.settings);
+    logger.log(chalk.green('  ✓ Config updated from server (issue-cert response)'));
+    return;
+  }
+  logger.log(chalk.gray('  Fetching settings...'));
+  try {
+    if (keyPem && typeof keyPem === 'string') {
+      logger.log(chalk.gray('  Using client certificate for TLS'));
+    }
+    const settings = await devApi.getSettings(baseUrl, issueResponse.certificate, keyPem);
+    await config.mergeRemoteSettings(settings);
+    logger.log(chalk.green('  ✓ Config updated from server'));
+  } catch (err) {
+    const msg = err.status === 400 ? getBadRequestHint() : (err.message || String(err));
+    logger.log(chalk.yellow('  ⚠ Could not fetch settings (server may not support cert yet): ' + msg));
+    logCertTroubleshootingHint(configDir, devId, baseUrl);
+  }
+}
+
+/**
+ * Run dev init: validate PIN via issue-cert, save certificate, fetch settings, add SSH key.
+ * @param {Object} options - Commander options (devId, server, pin)
+ * @returns {Promise<void>}
+ */
+async function runDevInit(options) {
+  const { baseUrl, devId } = validateInitOptions(options);
+  logger.log(chalk.blue('\n🔐 Onboarding with Builder Server...\n'));
+
+  try {
+    await devApi.getHealth(baseUrl);
+  } catch (err) {
+    throw new Error(`Cannot reach Builder Server at ${baseUrl}. Check URL and network. ${err.message}`);
+  }
+
+  logger.log(chalk.gray('  Generating certificate request...'));
+  const { csrPem, keyPem } = generateCSR(devId);
+
+  logger.log(chalk.gray('  Requesting certificate (issue-cert)...'));
+  const issueResponse = await requestCertificate(baseUrl, devId, options.pin, csrPem);
+
+  const configDir = getConfigDirForPaths();
+  const caPem = issueResponse.caCertificate || issueResponse.ca;
+  await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
+
+  await config.setRemoteServer(baseUrl);
+
+  await applySettingsFromServer(baseUrl, devId, issueResponse, keyPem);
+  await _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId);
+  logger.log(chalk.green('\n✓ Onboarding complete. You can use remote Docker and Mutagen sync.\n'));
+}
+
+/** Days before cert expiry at which we auto-refresh on dev refresh. */
+const CERT_REFRESH_DAYS = 14;
+
+/**
+ * True if the cert in certDir expires within CERT_REFRESH_DAYS (or we cannot read expiry).
+ * @param {string} certDir - Certificate directory
+ * @returns {boolean}
+ */
+function shouldRefreshDevCert(certDir) {
+  const validNotAfter = getCertValidNotAfter(certDir);
+  if (!validNotAfter) return true;
+  const now = Date.now();
+  const threshold = now + CERT_REFRESH_DAYS * 24 * 60 * 60 * 1000;
+  return validNotAfter.getTime() < threshold;
+}
+
+/**
+ * Refresh developer certificate: create PIN (with current cert), issue new cert, save and apply settings.
+ * @param {{ serverUrl: string, clientCertPem: string }} auth - Current auth from getRemoteDevAuth
+ * @returns {Promise<void>}
+ */
+async function runCertificateRefresh(auth) {
+  const devId = await config.getDeveloperId();
+  if (!devId) throw new Error('developer-id not set in config.');
+  const configDir = getConfigDirForPaths();
+  logger.log(chalk.blue('\n🔄 Refreshing certificate (create PIN + issue-cert)...\n'));
+  const pinRes = await devApi.createPin(auth.serverUrl, auth.clientCertPem, devId);
+  const pin = pinRes.pin;
+  if (!pin || typeof pin !== 'string') throw new Error('Server did not return a PIN.');
+  logger.log(chalk.gray('  Generating new certificate request...'));
+  const { csrPem, keyPem } = generateCSR(devId);
+  logger.log(chalk.gray('  Requesting new certificate (issue-cert)...'));
+  const issueResponse = await requestCertificate(auth.serverUrl, devId, pin, csrPem);
+  const caPem = issueResponse.caCertificate || issueResponse.ca;
+  await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
+  await applySettingsFromServer(auth.serverUrl, devId, issueResponse, keyPem);
+  logger.log(chalk.green('✓ Certificate refreshed and config updated from server.\n'));
+}
+
+/**
+ * Fetch settings from Builder Server and merge into config (GET /api/dev/settings).
+ * If certificate expires within CERT_REFRESH_DAYS (or --cert), refresh cert first (create PIN + issue-cert).
+ * @param {Object} [options] - Commander options; options.cert = true forces cert refresh
+ * @returns {Promise<void>}
+ * @throws {Error} If remote server or certificate not configured, or getSettings fails
+ */
+async function runDevRefresh(options = {}) {
+  const { getRemoteDevAuth } = require('../utils/remote-dev-auth');
+  const auth = await getRemoteDevAuth();
+  if (!auth) {
+    throw new Error('Remote server is not configured. Set remote-server and run "aifabrix dev init" first.');
+  }
+  const devId = await config.getDeveloperId();
+  const configDir = getConfigDirForPaths();
+  const certDir = getCertDir(configDir, devId);
+  const clientCertPem = readClientCertPem(certDir);
+  const clientKeyPem = readClientKeyPem(certDir);
+  if (!clientCertPem) {
+    throw new Error('Client certificate not found. Run "aifabrix dev init" first.');
+  }
+  const forceCertRefresh = Boolean(options.cert);
+  if (forceCertRefresh || shouldRefreshDevCert(certDir)) {
+    await runCertificateRefresh(auth);
+    return;
+  }
+  logger.log(chalk.blue('\n🔄 Fetching settings from Builder Server...\n'));
+  const settings = await devApi.getSettings(auth.serverUrl, clientCertPem, clientKeyPem || undefined);
+  await config.mergeRemoteSettings(settings);
+  logger.log(chalk.green('✓ Config updated from server. Run "aifabrix dev config" to verify.\n'));
+}
+
+module.exports = { runDevInit, runDevRefresh };

package/lib/commands/secrets-list.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview aifabrix secret list – list secret keys and values (user file, shared file, or remote API)
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { getAifabrixSecretsPath } = require('../core/config');
+const pathsUtil = require('../utils/paths');
+const { isRemoteSecretsUrl, getRemoteDevAuth } = require('../utils/remote-dev-auth');
+const devApi = require('../api/dev.api');
+
+const REMOTE_NOT_CONFIGURED_MSG = 'Remote server is not configured. Set remote-server and run "aifabrix dev init" first.';
+
+/**
+ * List secret keys and values from a YAML file.
+ * @param {string} filePath - Absolute path to secrets file
+ * @returns {Array<{ key: string, value: string }>} Key-value pairs (value stringified)
+ */
+function listKeysAndValuesFromFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = yaml.load(content) || {};
+    if (typeof data !== 'object' || Array.isArray(data)) return [];
+    return Object.entries(data).map(([key, val]) => ({
+      key,
+      value: (val !== null && val !== undefined) ? String(val) : ''
+    }));
+  } catch {
+    return [];
+  }
+}
+
+const KEY_COL_WIDTH = 45;
+const TABLE_SEPARATOR_LENGTH = 120;
+
+/**
+ * Log a list of secret keys and values as a table (header, column headers, separator, rows).
+ * Keys are sorted alphabetically. Matches datasource list style.
+ * @param {string} emptyMessage - Message when items.length === 0
+ * @param {string} title - Table title (e.g. "User secrets")
+ * @param {Array<{ key: string, value: string }>} items - Key-value pairs
+ */
+function logKeyValueList(emptyMessage, title, items) {
+  if (items.length === 0) {
+    logger.log(chalk.gray(emptyMessage));
+    return;
+  }
+  logger.log(chalk.bold(`\n📋 ${title}:\n`));
+  logger.log(chalk.gray('Key'.padEnd(KEY_COL_WIDTH) + 'Value'));
+  logger.log(chalk.gray('-'.repeat(TABLE_SEPARATOR_LENGTH)));
+  const sorted = [...items].sort((a, b) => a.key.localeCompare(b.key, undefined, { sensitivity: 'base' }));
+  sorted.forEach(({ key, value }) => {
+    const keyCol = key.padEnd(KEY_COL_WIDTH);
+    logger.log(`${keyCol}${value}`);
+  });
+  logger.log('');
+}
+
+/**
+ * List shared secrets (remote API or file) and log key and value.
+ * @param {string} generalSecretsPath - Path or URL for shared secrets
+ * @returns {Promise<void>}
+ */
+async function listSharedSecrets(generalSecretsPath) {
+  if (isRemoteSecretsUrl(generalSecretsPath)) {
+    const auth = await getRemoteDevAuth();
+    if (!auth) {
+      throw new Error(REMOTE_NOT_CONFIGURED_MSG);
+    }
+    const items = await devApi.listSecrets(auth.serverUrl, auth.clientCertPem);
+    const keyValues = items.map(i => ({ key: i.name || i.key || '', value: (i.value !== null && i.value !== undefined) ? String(i.value) : '' }));
+    logKeyValueList('No shared secrets (remote).', 'Shared secrets (remote)', keyValues);
+    return;
+  }
+  const resolvedPath = path.isAbsolute(generalSecretsPath)
+    ? generalSecretsPath
+    : path.resolve(process.cwd(), generalSecretsPath);
+  const keyValues = listKeysAndValuesFromFile(resolvedPath);
+  const fileTitle = `Shared secrets (file: ${resolvedPath})`;
+  logKeyValueList('No shared secrets in file.', fileTitle, keyValues);
+}
+
+/** List user secrets and log key and value. */
+function listUserSecrets() {
+  const userSecretsPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
+  const keyValues = listKeysAndValuesFromFile(userSecretsPath);
+  logKeyValueList('No user secrets.', 'User secrets', keyValues);
+}
+
+/**
+ * Handle secret list command. Lists key and value for each secret.
+ * @param {Object} options - Command options
+ * @param {boolean} [options.shared] - If true, list shared secrets (file or remote API)
+ * @returns {Promise<void>}
+ */
+async function handleSecretsList(options) {
+  const isShared = options.shared || options['shared'] || false;
+
+  if (isShared) {
+    const generalSecretsPath = await getAifabrixSecretsPath();
+    if (!generalSecretsPath) {
+      throw new Error('Shared secrets not configured. Set aifabrix-secrets in config.yaml.');
+    }
+    await listSharedSecrets(generalSecretsPath);
+  } else {
+    listUserSecrets();
+  }
+}
+
+module.exports = { handleSecretsList };