@aifabrix/builder 2.57.0 → 2.59.0

package/lib/commands/agent-kit-help.js

@@ -16,6 +16,7 @@ Coding hosts (--host) are Cursor, Claude Code, and/or Codex in this workspace.
 GitHub remotes are a separate command (agent-kit remote create).
 
 Examples:
+  $ aifabrix agent-kit setup https://controller.example.com
   $ aifabrix agent-kit init cust-demo --host all --approve-all --yes
   $ aifabrix agent-kit install --host claude --approve-all --yes
   $ aifabrix agent-kit install --host all --approve-all claude --yes
@@ -94,10 +95,12 @@ Silent remote: --host all --remote --org <owner> --yes
 const REMOTE_GROUP_HELP = `
 This is GitHub only: create origin and push this workspace.
 It does not choose Cursor, Claude Code, or Codex.
+For an existing GitHub repository on a managed host, use af onboarding --repo owner/name.
 
 Examples:
-  $ aifabrix agent-kit remote create
-  $ aifabrix agent-kit remote create --org my-org --yes
+  $ cd ~/agent-kit-workspace && af agent-kit remote create --org my-org --name my-repo --yes
+  $ af onboarding --repo my-org/existing-repo
+  $ af onboarding --repo my-org/new-repo
   $ aifabrix agent-kit install --host claude --approve-all --yes
   $ aifabrix agent-kit install --host codex --approve-all --yes
   $ aifabrix agent-kit install --host all --approve-all claude --yes
@@ -105,12 +108,16 @@ Examples:
 
 const REMOTE_HELP = `
 Creates a GitHub repository (origin) and pushes this workspace.
+Run inside the local workspace. --name sets the new GitHub repository name;
+omit it to use the workspace folder name. This command does not clone an
+existing GitHub repository.
 Not coding-host selection — use --host on install/update for Claude or Codex.
 
 Examples:
-  $ cd cust-demo && aifabrix agent-kit remote create
-  $ aifabrix agent-kit remote create --org my-org --yes
-  $ aifabrix agent-kit remote create --org my-org --dry-run --json
+  $ cd ~/agent-kit-workspace && af agent-kit remote create --org my-org --name my-repo --yes
+  $ af agent-kit remote create --org my-org --name my-repo --dry-run --json
+  $ af onboarding --repo my-org/existing-repo
+  $ af onboarding --repo my-org/new-repo
 
 Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
 `;
@@ -134,7 +141,10 @@ Examples:
 `;
 
 const LIST_HELP = `
-Lists every active tmux session visible to the current Unix user.
+Lists active tmux sessions and direct Codex app servers owned by the current
+Unix user. On a terminal, choose a tmux session to attach or Close. Codex app
+servers are shown as information and cannot be selected from this menu.
+--json and non-interactive output print the report without a prompt.
 
 Examples:
   $ aifabrix agent-kit list
@@ -142,9 +152,13 @@ Examples:
 `;
 
 const KILL_HELP = `
-Stops exactly one tmux session. Use agent-kit list to find its name.
+Stops exactly one tmux session by name. Omit the name in an interactive
+terminal to choose a tmux session or Codex app server. Stopping a Codex app
+server requires confirmation and may disconnect an active desktop chat.
+Pass an exact tmux name for scripts or --json.
 
 Examples:
+  $ aifabrix agent-kit kill
   $ aifabrix agent-kit kill aifabrix-miso
   $ aifabrix agent-kit kill aifabrix-miso --json
 `;

package/lib/commands/agent-kit-sessions.js

@@ -0,0 +1,126 @@
+/** CLI actions for listing, attaching, and stopping Agent Kit sessions. */
+'use strict';
+
+const inquirer = require('inquirer');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { formatSuccessLine } = require('../utils/cli-layout-chalk');
+const { runList, runKill, runAttach } = require('../agent-kit/tmux-sessions');
+const { listCodexAppServers, stopCodexAppServer } = require('../agent-kit/codex-app-server');
+const { formatSessionList, formatMissingKillName } = require('../agent-kit/session-report');
+const { LIST_HELP, KILL_HELP } = require('./agent-kit-help');
+
+function emitListReport(report, asJson) {
+  logger.log(asJson ? JSON.stringify(report, null, 2) : formatSessionList(report));
+}
+
+function emitKillReport(report, asJson) {
+  logger.log(asJson ? JSON.stringify(report, null, 2)
+    : formatSuccessLine(report.kind === 'codex-app-server'
+      ? `Sent stop signal to Codex app server PID ${report.pid}`
+      : `Stopped tmux session ${report.session}`));
+}
+
+function listSessions(options = {}) {
+  const report = (options.runList || runList)(options);
+  const codexServers = (options.listCodexAppServers || listCodexAppServers)(options);
+  return { ...report, codexServers, serverCount: codexServers.length };
+}
+
+async function runListLeaf(options = {}) {
+  try {
+    const report = listSessions(options);
+    emitListReport(report, Boolean(options.json));
+    const tty = options.isTTY === undefined
+      ? Boolean(process.stdin.isTTY && process.stdout.isTTY) : options.isTTY;
+    if (!tty || options.json || report.sessions.length === 0) return;
+    const choices = report.sessions.map(session => ({
+      name: `${session.name} (${session.attached ? 'attached' : 'detached'})`, value: session.name
+    }));
+    choices.push({ name: 'Close', value: null });
+    const answer = await (options.prompt || inquirer.prompt)([{
+      type: 'list', name: 'name', message: 'Attach to a tmux session:', choices
+    }]);
+    if (answer.name) (options.runAttach || runAttach)({ ...options, name: answer.name });
+  } catch (error) {
+    handleCommandError(error, 'agent-kit list');
+    process.exitCode = 1;
+  }
+}
+
+async function selectKillSession(options = {}) {
+  const tty = options.isTTY === undefined
+    ? Boolean(process.stdin.isTTY && process.stdout.isTTY) : options.isTTY;
+  if (!tty || options.json) return { state: 'missing' };
+  const report = listSessions(options);
+  emitListReport(report, false);
+  if (report.sessions.length + report.codexServers.length === 0) return { state: 'empty' };
+  const choices = report.sessions.map(session => ({
+    name: `tmux: ${session.name} (${session.attached ? 'attached' : 'detached'})`,
+    value: { kind: 'tmux', name: session.name }
+  }));
+  report.codexServers.forEach(server => choices.push({
+    name: `Codex app server (PID ${server.pid})`,
+    value: { kind: 'codex-app-server', ...server }
+  }));
+  choices.push({ name: 'Cancel', value: null });
+  const answer = await (options.prompt || inquirer.prompt)([{
+    type: 'list', name: 'selection', message: 'Select one session to stop:', choices
+  }]);
+  if (!answer.selection) return { state: 'cancelled' };
+  if (answer.selection.kind === 'codex-app-server') {
+    const confirm = await (options.prompt || inquirer.prompt)([{
+      type: 'confirm', name: 'stop', default: false,
+      message: `Stop Codex app server PID ${answer.selection.pid}? This may disconnect this chat; the client may reconnect.`
+    }]);
+    if (!confirm.stop) return { state: 'cancelled' };
+  }
+  return { state: 'selected', ...answer.selection };
+}
+
+function addListCommand(group) {
+  group.command('list')
+    .description('List sessions and choose a tmux session to attach')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', LIST_HELP)
+    .action(runListLeaf);
+}
+
+function addKillCommand(group) {
+  group.command('kill [name]')
+    .description('Stop a tmux session by name, or choose a session interactively')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', KILL_HELP)
+    .action(runKillLeaf);
+}
+
+async function runKillLeaf(name, options = {}) {
+  try {
+    const selection = name ? { state: 'selected', kind: 'tmux', name } : await selectKillSession(options);
+    if (selection.state === 'missing') {
+      const report = formatMissingKillName(Boolean(options.json));
+      logger.error(report.stderr);
+      if (report.stdout) logger.log(report.stdout);
+      process.exitCode = 1;
+      return;
+    }
+    if (selection.state === 'empty' || selection.state === 'cancelled') {
+      logger.log('No session stopped.');
+      return;
+    }
+    const report = selection.kind === 'codex-app-server'
+      ? (options.stopCodexAppServer || stopCodexAppServer)(selection, options)
+      : (options.runKill || runKill)({ ...options, name: selection.name });
+    emitKillReport(report, Boolean(options.json));
+  } catch (error) {
+    handleCommandError(error, 'agent-kit kill');
+    process.exitCode = 1;
+  }
+}
+
+function addSessionCommands(group) {
+  addListCommand(group);
+  addKillCommand(group);
+}
+
+module.exports = { addSessionCommands, listSessions, runListLeaf, selectKillSession, runKillLeaf };

package/lib/commands/agent-kit-setup.js

@@ -0,0 +1,44 @@
+/** Minimal setup command: controller required, local Codex workspace by default. */
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatBlockingError } = require('../utils/cli-layout-chalk');
+const { maskSensitiveData } = require('../utils/log-redaction');
+const { runSetup } = require('../agent-kit/setup');
+
+const SETUP_HELP = `
+Start onboarding with only a Controller URL. Defaults to Codex and a local Git
+workspace under the AI Fabrix work directory; GitHub is not required.
+If the work directory is unset, setup asks once and saves it.
+
+Examples:
+  $ aifabrix agent-kit setup https://controller.example.com
+  $ aifabrix agent-kit setup https://controller.example.com --code claude
+  $ aifabrix agent-kit setup https://controller.example.com --repo example-org/example-workspace
+
+With --repo owner/name, setup reuses a matching local checkout, clones an accessible
+remote, or creates a private repository and pushes. Unresolved access stops safely.
+Without --repo, files stay local and no GitHub login or push occurs.
+Folder name is the repository name, or workspace without --repo. Change environment with
+aifabrix auth --set-environment <environment>.
+Requires an interactive Linux/macOS terminal, git and tmux (gh only for GitHub).
+Installing a missing Claude CLI through npm requires Node.js 22+.
+`;
+
+function addSetupCommand(group) {
+  group.command('setup <controllerUrl>')
+    .description('Onboard a local Codex workspace; optionally use Claude or GitHub')
+    .option('--repo <owner/name>', 'GitHub repository to reuse, clone, or create privately')
+    .option('--code <agent>', 'Coding agent: codex or claude', 'codex')
+    .addHelpText('after', SETUP_HELP)
+    .action(async(controllerUrl, options) => {
+      try {
+        await runSetup({ ...options, controllerUrl });
+      } catch (error) {
+        logger.error(formatBlockingError(maskSensitiveData(error.message)));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { addSetupCommand, SETUP_HELP };

package/lib/commands/agent-kit.js

@@ -1,5 +1,4 @@
 /** `aifabrix agent-kit` command group. */
-
 'use strict';
 
 const logger = require('../utils/logger');
@@ -11,8 +10,8 @@ const {
 } = require('../utils/cli-layout-chalk');
 const { runInstall, runUpdate } = require('../agent-kit/run');
 const { runStart } = require('../agent-kit/start');
-const { runList, runKill } = require('../agent-kit/tmux-sessions');
-const { formatSessionList, formatMissingKillName } = require('../agent-kit/session-report');
+const { addSetupCommand } = require('./agent-kit-setup');
+const { addSessionCommands } = require('./agent-kit-sessions');
 const path = require('path');
 const { runInit, runRemoteCreate } = require('../agent-kit/init');
 const { enrichInitHostOptions, enrichInitRemoteOptions, enrichRemoteOptions, enrichApproveAllOptions } = require('../agent-kit/remote-prompts');
@@ -33,8 +32,6 @@ const {
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
   START_HELP,
-  LIST_HELP,
-  KILL_HELP,
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP
 } = require('./agent-kit-help');
@@ -131,32 +128,6 @@ function emitStartReport(json, asJson) {
   logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Ready'));
 }
 
-/**
- * @param {object} json
- * @param {boolean} asJson
- * @returns {void}
- */
-function emitListReport(json, asJson) {
-  if (asJson) {
-    logger.log(JSON.stringify(json, null, 2));
-    return;
-  }
-  logger.log(formatSessionList(json));
-}
-
-/**
- * @param {object} json
- * @param {boolean} asJson
- * @returns {void}
- */
-function emitKillReport(json, asJson) {
-  if (asJson) {
-    logger.log(JSON.stringify(json, null, 2));
-    return;
-  }
-  logger.log(formatSuccessLine(`Stopped tmux session ${json.session}`));
-}
-
 /**
  * @param {Function} runner
  * @param {object} options
@@ -185,6 +156,7 @@ function setupAgentKitCommands(program) {
     .description('Install, init, and update the AI Fabrix Agent Kit in a customer workspace')
     .addHelpText('after', GROUP_HELP);
 
+  addSetupCommand(group);
   addInitCommand(group);
   addInstallCommand(group);
   addStatusCommand(group);
@@ -192,8 +164,7 @@ function setupAgentKitCommands(program) {
   addValidateCommand(group);
   addRemoteCommand(group);
   addStartCommand(group);
-  addListCommand(group);
-  addKillCommand(group);
+  addSessionCommands(group);
 }
 
 /**
@@ -254,7 +225,7 @@ function addRemoteCommand(group) {
     .command('create')
     .description('Create a private GitHub repository (origin) and push this workspace')
     .option('--org <owner>', 'Hosting org or user (required when non-TTY)')
-    .option('--name <repo>', 'Remote repository name (default: directory basename)')
+    .option('--name <repo>', 'New GitHub repository name (default: workspace folder name)')
     .option('--visibility <mode>', 'private or public', 'private')
     .option('--yes', 'Silent: skip TTY confirmation (pair with --org)')
     .option('--dry-run', 'Plan without creating the remote')
@@ -451,49 +422,4 @@ function addStartCommand(group) {
     });
 }
 
-/**
- * @param {import('commander').Command} group
- */
-function addListCommand(group) {
-  group
-    .command('list')
-    .description('List active tmux sessions for the current user')
-    .option('--json', 'Machine-readable output')
-    .addHelpText('after', LIST_HELP)
-    .action(async(options) => {
-      try {
-        emitListReport(runList(options), Boolean(options.json));
-      } catch (error) {
-        handleCommandError(error, 'agent-kit list');
-        process.exitCode = 1;
-      }
-    });
-}
-
-/**
- * @param {import('commander').Command} group
- */
-function addKillCommand(group) {
-  group
-    .command('kill [name]')
-    .description('Stop one tmux session by exact name')
-    .option('--json', 'Machine-readable output')
-    .addHelpText('after', KILL_HELP)
-    .action(async(name, options) => {
-      if (!name) {
-        const report = formatMissingKillName(Boolean(options.json));
-        logger.error(report.stderr);
-        if (report.stdout) logger.log(report.stdout);
-        process.exitCode = 1;
-        return;
-      }
-      try {
-        emitKillReport(runKill({ ...options, name }), Boolean(options.json));
-      } catch (error) {
-        handleCommandError(error, 'agent-kit kill');
-        process.exitCode = 1;
-      }
-    });
-}
-
 module.exports = { setupAgentKitCommands };

package/lib/commands/dev-init.js

@@ -29,13 +29,13 @@ const {
   isLinuxCaSudoRequiredError
 } = require('../utils/dev-ca-install');
 const { runOptionalHostsSetup } = require('../utils/dev-hosts-helper');
-const { mergeDevSshConfigAfterInit } = require('../utils/dev-init-ssh-merge');
+const { mergeDevSshConfigAfterInit, hostnameFromBaseUrl } = require('../utils/dev-init-ssh-merge');
 const { resolveInitOptions } = require('../utils/dev-init-resolve');
 const {
   isHealthHttpServerError,
   formatEnsureServerTrustedFailure
 } = require('../utils/dev-init-health-messages');
-const { getBadRequestHint, logCertTroubleshootingHint } = require('../utils/dev-init-cert-hints');
+const { getBadRequestHint } = require('../utils/dev-init-cert-hints');
 const { augmentAndSaveCaPemForRemoteDocker } = require('../utils/dev-ca-docker-augment');
 
 /**
@@ -249,7 +249,7 @@ async function _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, config
   } 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);
+    throw new Error(`Onboarding incomplete for developer ${devId}: SSH key registration failed. Ask the server administrator to check role access, then retry dev init with a new PIN.`);
   }
 }
 
@@ -262,24 +262,23 @@ async function _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, config
  * @param {string} [serverCaPem] - Dev root CA for Node TLS
  */
 async function applySettingsFromServer(baseUrl, devId, issueResponse, keyPem, serverCaPem) {
-  const configDir = getConfigDirForPaths();
-  if (issueResponse.settings && typeof issueResponse.settings === 'object') {
-    await config.mergeRemoteSettings(issueResponse.settings);
-    logger.log(chalk.green('  ') + formatSuccessLine('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'));
+    let settings = issueResponse.settings;
+    if (!settings) {
+      logger.log(chalk.gray('  Fetching settings...'));
+      settings = await devApi.getSettings(baseUrl, issueResponse.certificate, keyPem, serverCaPem);
     }
-    const settings = await devApi.getSettings(baseUrl, issueResponse.certificate, keyPem, serverCaPem);
-    await config.mergeRemoteSettings(settings);
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Server settings are missing or invalid.');
+    const fresh = { ...settings, 'developer-id': devId, 'remote-server': baseUrl,
+      'sync-ssh-user': settings['sync-ssh-user'] || `dev${devId}`,
+      'sync-ssh-host': settings['sync-ssh-host'] || hostnameFromBaseUrl(baseUrl) };
+    await config.mergeRemoteSettings(fresh);
     logger.log(chalk.green('  ') + formatSuccessLine('Config updated from server'));
+    return fresh;
   } 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);
+    logger.log(chalk.yellow('  ⚠ Could not fetch settings: ' + msg));
+    throw new Error(`Onboarding incomplete for developer ${devId}: current server settings could not be applied. Saved settings from another developer will not be used. Ask the server administrator to check role access, then retry dev init with a new PIN.`);
   }
 }
 
@@ -317,7 +316,7 @@ async function resolveServerCaPemForTls(baseUrl, options) {
  * @param {{ hostAlias: string|null, syncUser: string, syncHost: string|null }} p
  */
 function logOnboardingFinished({ hostAlias, syncUser, syncHost }) {
-  logger.log(formatSuccessParagraph('Onboarding complete. You can use remote Docker and Mutagen sync.'));
+  logger.log(formatSuccessParagraph('Certificate, server settings and SSH key registration complete. Access depends on your server permissions.'));
   if (hostAlias) {
     logger.log(
       chalk.gray('  You can also open an SSH session on the builder with ') +
@@ -367,14 +366,13 @@ async function runDevInit(options) {
   );
   await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
 
-  await applySettingsFromServer(baseUrl, devId, issueResponse, keyPem, serverCaPemForTls || undefined);
-  await augmentAndSaveCaPemForRemoteDocker(configDir, devId, caPem, {
-    settings: issueResponse.settings,
-    remoteServerUrl: baseUrl,
+  const settings = await applySettingsFromServer(baseUrl, devId, issueResponse, keyPem, serverCaPemForTls || undefined);
+  await _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId, serverCaPemForTls || undefined);
+  if (settings['docker-endpoint']) await augmentAndSaveCaPemForRemoteDocker(configDir, devId, caPem, {
+    settings,
     warn: (msg) => logger.log(chalk.yellow(`  ⚠ ${msg}`))
   });
-  await _runSshKeyRegistrationStep(baseUrl, issueResponse, keyPem, configDir, devId, serverCaPemForTls || undefined);
-  const sshInfo = await mergeDevSshConfigAfterInit(baseUrl, devId);
+  const sshInfo = await mergeDevSshConfigAfterInit(baseUrl, devId, settings);
   logOnboardingFinished(sshInfo);
 }
 

package/lib/commands/dev-refresh.js

@@ -82,9 +82,9 @@ async function runCertificateRefresh(auth) {
   const issueResponse = await requestCertificate(auth.serverUrl, devId, pin, csrPem, serverCaPem);
   const caPem = mergeCaPemBlocks(serverCaPem, issueResponse.caCertificate, issueResponse.ca);
   await saveCertAndConfig(configDir, devId, issueResponse.certificate, keyPem, caPem);
-  await applySettingsFromServer(auth.serverUrl, devId, issueResponse, keyPem, serverCaPem);
+  const settings = await applySettingsFromServer(auth.serverUrl, devId, issueResponse, keyPem, serverCaPem);
   await augmentAndSaveCaPemForRemoteDocker(configDir, devId, caPem, {
-    settings: issueResponse.settings,
+    settings,
     remoteServerUrl: auth.serverUrl,
     warn: (msg) => logger.log(chalk.yellow(`  ⚠ ${msg}`))
   });

package/lib/commands/dev-registry.js

@@ -0,0 +1,155 @@
+/**
+ * `aifabrix dev set-registry` / `dev print-registry` logic.
+ *
+ * @fileoverview Installation registry preference and host-scoped credential management
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const config = require('../core/config');
+const logger = require('../utils/logger');
+const { formatSuccessLine, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { normalizeRegistryHost } = require('../utils/config-registry-preference');
+const registryCredentials = require('../utils/registry-credentials');
+
+/**
+ * Reads the whole of stdin (for --password-stdin).
+ * @param {NodeJS.ReadableStream} [stream] - Input stream
+ * @returns {Promise<string>}
+ */
+function readAllStdin(stream = process.stdin) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+      data += chunk;
+    });
+    stream.on('end', () => resolve(data));
+    stream.on('error', reject);
+  });
+}
+
+function hasOption(value) {
+  return value !== undefined && value !== null;
+}
+
+function assertModeOptions(registry, opts) {
+  const credentialOption = hasOption(opts.username) || hasOption(opts.password) || opts.passwordStdin === true;
+  if (opts.clear && opts.clearCredentials) {
+    throw new Error('Use either --clear or --clear-credentials, not both');
+  }
+  if ((opts.clear || opts.clearCredentials) && credentialOption) {
+    throw new Error('--clear and --clear-credentials cannot be combined with --username or a password option');
+  }
+  if (opts.clear && hasOption(registry)) {
+    throw new Error('--clear removes the saved registry and takes no registry argument');
+  }
+  if (!opts.clear && !(typeof registry === 'string' && registry.trim())) {
+    throw new Error('Registry is required (for example: aifabrix dev set-registry myregistry.azurecr.io)');
+  }
+}
+
+function assertCredentialOptions(opts) {
+  if (hasOption(opts.password) && opts.passwordStdin === true) {
+    throw new Error('Use either --password or --password-stdin, not both');
+  }
+  const passwordGiven = hasOption(opts.password) || opts.passwordStdin === true;
+  if (hasOption(opts.username) !== passwordGiven) {
+    throw new Error('--username and a password (--password or --password-stdin) must be supplied together');
+  }
+  if (hasOption(opts.username) && !String(opts.username).trim()) {
+    throw new Error('--username must not be empty');
+  }
+  if (hasOption(opts.password) && String(opts.password) === '') {
+    throw new Error('--password must not be empty');
+  }
+  return passwordGiven;
+}
+
+async function resolvePassword(opts, readStdin) {
+  if (opts.passwordStdin !== true) return String(opts.password);
+  const password = (await readStdin()).replace(/\r?\n$/, '');
+  if (!password) {
+    throw new Error('--password-stdin received an empty password');
+  }
+  return password;
+}
+
+async function saveWithCredentials(host, username, password) {
+  const saved = await registryCredentials.saveRegistryCredentials(host, username, password);
+  try {
+    await config.setRegistry(host);
+  } catch (error) {
+    saved.rollback();
+    throw new Error(`Could not save the registry preference; credentials for ${host} were restored (${error.message})`);
+  }
+}
+
+async function runClearMode(registry, opts) {
+  if (opts.clear) {
+    await config.clearRegistry();
+    logger.log(formatSuccessLine('Registry cleared (application image.registry applies again)'));
+    return { action: 'clear', registry: null, credentials: false };
+  }
+  const host = normalizeRegistryHost(registry);
+  const removed = registryCredentials.removeRegistryCredentials(host);
+  logger.log(formatSuccessLine(removed ? `Credentials removed for ${host}` : `No stored credentials for ${host}`));
+  return { action: 'clear-credentials', registry: host, credentials: false };
+}
+
+/**
+ * Runs `dev set-registry`.
+ * @param {string|undefined} registry - Positional registry
+ * @param {Object} opts - Commander options
+ * @param {Object} [deps] - `readStdin` override (tests)
+ * @returns {Promise<{ action: string, registry: string|null, credentials: boolean }>}
+ */
+async function runSetRegistry(registry, opts = {}, deps = {}) {
+  assertModeOptions(registry, opts);
+  if (opts.clear || opts.clearCredentials) return runClearMode(registry, opts);
+  const host = normalizeRegistryHost(registry);
+  const withCredentials = assertCredentialOptions(opts);
+  if (!withCredentials) {
+    await config.setRegistry(host);
+    logger.log(formatSuccessLine(`Registry set to ${host}`));
+    return { action: 'set', registry: host, credentials: false };
+  }
+  const password = await resolvePassword(opts, deps.readStdin || readAllStdin);
+  await saveWithCredentials(host, String(opts.username).trim(), password);
+  logger.log(formatSuccessLine(`Registry set to ${host}`));
+  logger.log(formatSuccessLine(`Credentials saved for ${host} in your local secrets file (encrypted)`));
+  if (opts.passwordStdin !== true) {
+    logger.log(formatWarningLine('--password can appear in shell history and process listings; prefer --password-stdin'));
+  }
+  return { action: 'set', registry: host, credentials: true };
+}
+
+/**
+ * `dev print-registry`: the saved value plus a newline, or an empty line. Stdout only.
+ * @returns {Promise<void>}
+ */
+async function runPrintRegistry() {
+  const registry = await config.getRegistry();
+  process.stdout.write(`${registry || ''}\n`);
+}
+
+/**
+ * Safe credential status label for `dev show` (never decrypts).
+ * @param {string|null} registry - Saved registry
+ * @returns {string|null}
+ */
+function registryCredentialLabel(registry) {
+  if (!registry) return null;
+  try {
+    const status = registryCredentials.getRegistryCredentialStatus(registry);
+    if (status === 'complete') return 'configured';
+    if (status === 'absent') return 'not configured';
+    return `incomplete (run: aifabrix dev set-registry ${registry} --clear-credentials)`;
+  } catch {
+    return 'unknown';
+  }
+}
+
+module.exports = { runSetRegistry, runPrintRegistry, registryCredentialLabel, readAllStdin };