@aifabrix/builder 2.43.0 → 2.44.0

package/lib/cli/setup-dev-path-commands.js

@@ -0,0 +1,124 @@
+/**
+ * Dev subcommands: set-home, set-work, print-home, print-work, set-format.
+ *
+ * @fileoverview Path and format CLI registration for `aifabrix dev`
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+
+const chalk = require('chalk');
+const config = require('../core/config');
+const logger = require('../utils/logger');
+const paths = require('../utils/paths');
+const { registerAifabrixShellEnvFromConfig } = require('../utils/register-aifabrix-shell-env');
+const { handleCommandError } = require('../utils/cli-utils');
+
+async function runShellEnvRegistration() {
+  try {
+    await registerAifabrixShellEnvFromConfig(config.getConfig);
+    logger.log(
+      chalk.gray('  User/shell environment updated. Open a new terminal for AIFABRIX_HOME / AIFABRIX_WORK.')
+    );
+  } catch (regErr) {
+    throw new Error(`Config saved but environment registration failed: ${regErr.message}`);
+  }
+}
+
+function addSetHomeCommand(dev) {
+  dev
+    .command('set-home <path>')
+    .description('Set or clear aifabrix-home in config; register AIFABRIX_HOME for new shells unless --no-register-env')
+    .option('--no-register-env', 'Do not update Windows user env or POSIX shell profile hooks')
+    .action(async(homePath, cmdOpts) => {
+      try {
+        const trimmed = (homePath || '').trim();
+        await config.setAifabrixHomeOverride(trimmed);
+        logger.log(trimmed === '' ? formatSuccessLine('Home path cleared') : formatSuccessLine(`Home path set to ${trimmed}`));
+        if (cmdOpts?.registerEnv !== false) {
+          await runShellEnvRegistration();
+        }
+      } catch (error) {
+        handleCommandError(error, 'dev set-home');
+        process.exit(1);
+      }
+    });
+}
+
+function addSetWorkCommand(dev) {
+  dev
+    .command('set-work <path>')
+    .description('Set or clear aifabrix-work (workspace root) in config; register AIFABRIX_WORK unless --no-register-env')
+    .option('--no-register-env', 'Do not update Windows user env or POSIX shell profile hooks')
+    .action(async(workPath, cmdOpts) => {
+      try {
+        const trimmed = (workPath || '').trim();
+        await config.setAifabrixWorkOverride(trimmed);
+        logger.log(trimmed === '' ? formatSuccessLine('Work path cleared') : formatSuccessLine(`Work path set to ${trimmed}`));
+        if (cmdOpts?.registerEnv !== false) {
+          await runShellEnvRegistration();
+        }
+      } catch (error) {
+        handleCommandError(error, 'dev set-work');
+        process.exit(1);
+      }
+    });
+}
+
+function addPrintHomeWorkCommands(dev) {
+  dev
+    .command('print-home')
+    .description('Print resolved AIFABRIX_HOME path (stdout only; for scripts)')
+    .action(() => {
+      try {
+        process.stdout.write(`${paths.getAifabrixHome()}\n`);
+      } catch (error) {
+        handleCommandError(error, 'dev print-home');
+        process.exit(1);
+      }
+    });
+
+  dev
+    .command('print-work')
+    .description('Print resolved workspace path or empty line (stdout only; for scripts)')
+    .action(() => {
+      try {
+        const w = paths.getAifabrixWork();
+        process.stdout.write(w ? `${w}\n` : '\n');
+      } catch (error) {
+        handleCommandError(error, 'dev print-work');
+        process.exit(1);
+      }
+    });
+}
+
+function addSetFormatCommand(dev, handleSetFormat) {
+  dev
+    .command('set-format <format>')
+    .description('Default json|yaml when --format is omitted (download/convert)')
+    .action(async(format) => {
+      try {
+        await handleSetFormat(format);
+      } catch (error) {
+        handleCommandError(error, 'dev set-format');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Register dev set-home, set-work, print-*, set-format.
+ * @param {import('commander').Command} dev - dev subcommand group
+ * @param {function(string): Promise<void>} handleSetFormat - handler that updates format and refreshes display
+ * @returns {void}
+ */
+function setupDevPathAndFormatCommands(dev, handleSetFormat) {
+  addSetHomeCommand(dev);
+  addSetWorkCommand(dev);
+  addPrintHomeWorkCommands(dev);
+  addSetFormatCommand(dev, handleSetFormat);
+}
+
+module.exports = { setupDevPathAndFormatCommands };

package/lib/cli/setup-dev.js

@@ -1,3 +1,4 @@
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 /**
  * CLI developer configuration command setup (dev config, dev set-id, dev init, dev add/update/pin/delete/list).
  *
@@ -8,10 +9,11 @@
 
 const chalk = require('chalk');
 const config = require('../core/config');
-const devConfig = require('../utils/dev-config');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
+const { setupDevPathAndFormatCommands } = require('./setup-dev-path-commands');
 const { runDevInit, runDevRefresh } = require('../commands/dev-init');
+const { displayDevConfig } = require('../commands/dev-show-display');
 const {
   handleDevList,
   handleDevAdd,
@@ -20,45 +22,78 @@ const {
   handleDevDelete
 } = require('../commands/dev-cli-handlers');
 
-/**
- * Display developer configuration (local ports and config; remote/settings keys always shown).
- * Always shows environment, controller, and remote keys (value or "(not set)").
- * @param {string} devId - Developer ID
- * @returns {Promise<void>}
- */
-async function displayDevConfig(devId) {
-  const devIdNum = parseInt(devId, 10);
-  const ports = devConfig.getDevPorts(devIdNum);
-  const environment = await config.getCurrentEnvironment();
-  const controller = await config.getControllerUrl();
-
-  const optionalConfigVars = [
-    { key: 'format', value: (await config.getFormat()) ?? '(not set)' },
-    { key: 'aifabrix-home', value: await config.getAifabrixHomeOverride() },
-    { key: 'aifabrix-secrets', value: await config.getAifabrixSecretsPath() },
-    { key: 'aifabrix-env-config', value: await config.getAifabrixEnvConfigPath() },
-    { key: 'remote-server', value: await config.getRemoteServer() },
-    { key: 'docker-endpoint', value: await config.getDockerEndpoint() },
-    { key: 'user-mutagen-folder', value: await config.getUserMutagenFolder() },
-    { key: 'sync-ssh-user', value: await config.getSyncSshUser() },
-    { key: 'sync-ssh-host', value: await config.getSyncSshHost() }
-  ];
-
-  logger.log('\n🔧 Developer Configuration\n');
-  logger.log(`Developer ID: ${devId}`);
-  logger.log('\nPorts:');
-  logger.log(`  App: ${ports.app}`);
-  logger.log(`  Postgres: ${ports.postgres}`);
-  logger.log(`  Redis: ${ports.redis}`);
-  logger.log(`  pgAdmin: ${ports.pgadmin}`);
-  logger.log(`  Redis Commander: ${ports.redisCommander}`);
-
-  logger.log('\nConfiguration:');
-  logger.log(`  environment: '${environment}'`);
-  logger.log(controller ? `  controller: '${controller}'` : '  controller: (not set)');
-  optionalConfigVars.forEach(v => logger.log(`  ${v.key}: ${v.value || '(not set)'}`));
-  logger.log('');
-}
+/** Appended to `dev update --help` (examples + partial-update behaviour). */
+const DEV_UPDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix dev update 02 --name "Jane Doe"
+  $ aifabrix dev update --developer-id 02 --email jane@example.com
+  $ aifabrix dev update 01 --name "Admin" --groups admin,developer
+  $ aifabrix dev update 02 --groups admin,developer,docker
+
+Partial update: only flags you pass are sent to the server. Omitted name, email, and groups are left unchanged.
+`;
+
+/** Appended to `dev add --help` (examples + workflow). */
+const DEV_ADD_HELP_AFTER = `
+Examples:
+  $ aifabrix dev add --developer-id 02 --name "Jane Doe" --email jane@example.com
+  $ aifabrix dev add --developer-id 03 --name "Build admin" --email admin@example.com --groups admin,developer
+  $ aifabrix dev add --developer-id 04 --name "CI user" --email ci@example.com --groups secret-manager,developer
+
+Requires a configured remote Builder Server and an admin client certificate (same machine setup as dev list / dev pin). After add, run dev pin <id> once to create a PIN for aifabrix dev init.
+`;
+
+/** Appended to `aifabrix dev --help` (overview; keep subcommand .description lines short). */
+const DEV_GROUP_HELP_AFTER = `
+Categories:
+  Local config   show, set-id, set-scoped-resources, set-env-config, set-home, set-work, set-format, print-home, print-work
+  Onboarding     init (PIN onboarding), refresh (sync settings / renew cert)
+  Remote admin   list, add, update, pin, delete  (need remote-server + client cert in ~/.aifabrix)
+  Sync / stop    down  (Mutagen; optional --apps for containers)
+
+Use: aifabrix dev <command> --help
+`;
+
+/** Appended to `dev init --help`. */
+const DEV_INIT_HELP_AFTER = `
+Examples:
+  Full (first machine or no config yet):
+  $ aifabrix dev init --developer-id 01 --server https://builder01.local --pin <one-time-pin>
+
+  When remote-server and developer-id are already in ~/.aifabrix/config.yaml (from settings or dev show):
+  $ aifabrix dev init --pin <one-time-pin>
+
+Admin issues the PIN with: aifabrix dev pin <developer-id>
+`;
+
+/** Appended to `dev refresh --help`. */
+const DEV_REFRESH_HELP_AFTER = `
+Requires remote-server and saved client certificate (after dev init). Use --cert to force a new cert before expiry.
+`;
+
+/** Appended to `dev pin --help`. */
+const DEV_PIN_HELP_AFTER = `
+Examples:
+  $ aifabrix dev pin 02
+  $ aifabrix dev pin 02 --hosts-ip 192.168.1.25
+  $ aifabrix dev pin   (uses developer-id from config)
+
+Prints copy-paste commands for the developer: full dev init, hosts-file variant, and dev init --pin
+when their config already has remote-server + developer-id.
+`;
+
+/** Appended to `dev delete --help`. */
+const DEV_DELETE_HELP_AFTER = `
+Example:
+  $ aifabrix dev delete 02
+`;
+
+/** Appended to `dev down --help`. */
+const DEV_DOWN_HELP_AFTER = `
+Examples:
+  $ aifabrix dev down
+  $ aifabrix dev down --apps
+`;
 
 /**
  * Handle dev set-format command
@@ -67,7 +102,34 @@ async function displayDevConfig(devId) {
  */
 async function handleSetFormat(format) {
   await config.setFormat(format);
-  logger.log(chalk.green(`✓ Format set to ${format.toLowerCase()}`));
+  logger.log(formatSuccessLine(`Format set to ${format.toLowerCase()}`));
+  const devId = await config.getDeveloperId();
+  await displayDevConfig(devId);
+}
+
+/**
+ * Set useEnvironmentScopedResources in ~/.aifabrix/config.yaml
+ * @param {string} value - "true" or "false"
+ * @returns {Promise<void>}
+ */
+async function handleSetScopedResources(value) {
+  const b = String(value || '').trim().toLowerCase();
+  if (b !== 'true' && b !== 'false') {
+    throw new Error('Value must be true or false (example: aifabrix dev set-scoped-resources true)');
+  }
+  await config.setUseEnvironmentScopedResources(b === 'true');
+  if (b === 'true') {
+    logger.log(
+      formatSuccessLine('Environment-scoped resources activated in ~/.aifabrix/config.yaml')
+    );
+  } else {
+    logger.log(formatSuccessLine('Environment-scoped resources passivated (default local naming)'));
+  }
+  logger.log(
+    chalk.gray(
+      '  Apps still need environmentScopedResources: true in application.yaml for prefixing when you run with --env dev or tst.'
+    )
+  );
   const devId = await config.getDeveloperId();
   await displayDevConfig(devId);
 }
@@ -79,7 +141,7 @@ async function handleSetFormat(format) {
 function setupDevShowAndSetId(dev) {
   dev
     .command('show')
-    .description('Show developer configuration (ports and config vars)')
+    .description('Show dev ports and ~/.aifabrix config')
     .action(async() => {
       try {
         const devId = await config.getDeveloperId();
@@ -92,7 +154,7 @@ function setupDevShowAndSetId(dev) {
 
   dev
     .command('set-id <id>')
-    .description('Set developer ID (0 = default infra, > 0 = developer-specific)')
+    .description('Set developer ID (0 = default infra, >0 = dev-specific ports)')
     .action(async(id) => {
       try {
         const digitsOnly = /^[0-9]+$/.test(id);
@@ -101,56 +163,22 @@ function setupDevShowAndSetId(dev) {
         }
         await config.setDeveloperId(id);
         process.env.AIFABRIX_DEVELOPERID = id;
-        logger.log(chalk.green(`✓ Developer ID set to ${id}`));
+        logger.log(formatSuccessLine(`Developer ID set to ${id}`));
         await displayDevConfig(id);
       } catch (error) {
         handleCommandError(error, 'dev set-id');
         process.exit(1);
       }
     });
-}
-
-/**
- * Register dev set-env-config, set-home and set-format commands.
- * @param {Command} dev - dev subcommand group
- */
-function setupDevPathAndFormatCommands(dev) {
-  dev
-    .command('set-env-config <filePath>')
-    .description('Set aifabrix-env-config path in config.yaml (pass empty to clear; path is not checked for existence)')
-    .action(async(filePath) => {
-      try {
-        const trimmed = (filePath || '').trim();
-        await config.setAifabrixEnvConfigPath(trimmed);
-        logger.log(trimmed === '' ? chalk.green('✓ Env config path cleared') : chalk.green(`✓ Env config path set to ${trimmed}`));
-      } catch (error) {
-        handleCommandError(error, 'dev set-env-config');
-        process.exit(1);
-      }
-    });
 
   dev
-    .command('set-home <path>')
-    .description('Set aifabrix-home path in config.yaml (pass empty string to clear)')
-    .action(async(homePath) => {
+    .command('set-scoped-resources <value>')
+    .description('Set useEnvironmentScopedResources to true|false in ~/.aifabrix/config.yaml')
+    .action(async(value) => {
       try {
-        const trimmed = (homePath || '').trim();
-        await config.setAifabrixHomeOverride(trimmed);
-        logger.log(trimmed === '' ? chalk.green('✓ Home path cleared') : chalk.green(`✓ Home path set to ${trimmed}`));
+        await handleSetScopedResources(value);
       } catch (error) {
-        handleCommandError(error, 'dev set-home');
-        process.exit(1);
-      }
-    });
-
-  dev
-    .command('set-format <format>')
-    .description('Set default output format for download/convert (json | yaml); used when --format not passed')
-    .action(async(format) => {
-      try {
-        await handleSetFormat(format);
-      } catch (error) {
-        handleCommandError(error, 'dev set-format');
+        handleCommandError(error, 'dev set-scoped-resources');
         process.exit(1);
       }
     });
@@ -162,7 +190,29 @@ function setupDevPathAndFormatCommands(dev) {
  */
 function setupDevConfigCommands(dev) {
   setupDevShowAndSetId(dev);
-  setupDevPathAndFormatCommands(dev);
+  setupDevPathAndFormatCommands(dev, handleSetFormat);
+}
+
+/**
+ * Shared Commander options for dev init (PIN onboarding).
+ * @param {object} cmd - Commander command to attach options to
+ * @returns {object} Same command for chaining
+ */
+function addDevOnboardingOptions(cmd) {
+  return cmd
+    .requiredOption('--pin <pin>', 'One-time PIN from your admin (see aifabrix dev pin)')
+    .option(
+      '--developer-id <id>',
+      'Developer ID (optional if set in ~/.aifabrix/config.yaml and not 0; e.g. 01)'
+    )
+    .option('--server <url>', 'Builder Server base URL (optional if remote-server is in config)')
+    .option('-y, --yes', 'Auto-install development CA without prompt when certificate is untrusted; with --add-hosts, skip hosts-file confirmation')
+    .option('--no-install-ca', 'Do not offer CA install; fail with manual instructions on untrusted certificate')
+    .option(
+      '--add-hosts',
+      'Offer to add the server hostname to this machine\'s hosts file (wildcard DNS must be configured separately; may require admin)'
+    )
+    .option('--hosts-ip <ip>', 'IPv4 for the hosts entry when using --add-hosts (skips lookup / IP prompt)');
 }
 
 /**
@@ -170,26 +220,26 @@ function setupDevConfigCommands(dev) {
  * @param {Command} dev - dev subcommand group
  */
 function setupDevInitCommand(dev) {
-  dev
-    .command('init')
-    .description('Onboard with Builder Server (issue certificate, fetch settings, register SSH key for Mutagen)')
-    .requiredOption('--developer-id <id>', 'Developer ID (same as dev add; e.g. 01)')
-    .requiredOption('--server <url>', 'Builder Server base URL (e.g. https://dev.aifabrix.dev)')
-    .requiredOption('--pin <pin>', 'One-time PIN from your admin')
-    .option('-y, --yes', 'Auto-install development CA without prompt when certificate is untrusted')
-    .option('--no-install-ca', 'Do not offer CA install; fail with manual instructions on untrusted certificate')
-    .action(async(options) => {
-      try {
-        await runDevInit(options);
-      } catch (error) {
-        handleCommandError(error, 'dev init');
-        process.exit(1);
-      }
-    });
+  const runOnboarding = async(options, label) => {
+    try {
+      await runDevInit(options);
+    } catch (error) {
+      handleCommandError(error, label);
+      process.exit(1);
+    }
+  };
+
+  addDevOnboardingOptions(
+    dev
+      .command('init')
+      .description('Onboard with Builder Server (cert, settings, SSH for Mutagen)')
+      .addHelpText('after', DEV_INIT_HELP_AFTER)
+  ).action(async(options) => runOnboarding(options, 'dev init'));
 
   dev
     .command('refresh')
-    .description('Fetch settings from Builder Server and update config; refresh certificate if expiring within 14 days or --cert')
+    .description('Pull server settings into config; renew cert if due or --cert')
+    .addHelpText('after', DEV_REFRESH_HELP_AFTER)
     .option('--cert', 'Force certificate refresh (create PIN + issue-cert) even when cert is still valid')
     .action(async(options) => {
       try {
@@ -208,7 +258,7 @@ function setupDevInitCommand(dev) {
 function setupDevListAddCommands(dev) {
   dev
     .command('list')
-    .description('List developer users (remote Builder Server only)')
+    .description('List developers (remote Builder Server)')
     .action(async() => {
       try {
         await handleDevList();
@@ -220,11 +270,12 @@ function setupDevListAddCommands(dev) {
 
   dev
     .command('add')
-    .description('Register a new developer (remote Builder Server only; admin)')
-    .requiredOption('--developer-id <id>', 'Developer ID (unique, e.g. 01)')
+    .description('Create developer on server (admin); then dev pin for onboarding')
+    .requiredOption('--developer-id <id>', 'Unique id, digits only (e.g. 02); used with dev init --developer-id')
     .requiredOption('--name <name>', 'Display name')
     .requiredOption('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, developer)', 'developer')
+    .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, developer, docker', 'developer')
+    .addHelpText('after', DEV_ADD_HELP_AFTER)
     .action(async(options) => {
       try {
         await handleDevAdd(options);
@@ -242,11 +293,12 @@ function setupDevListAddCommands(dev) {
 function setupDevUpdatePinDeleteCommands(dev) {
   dev
     .command('update [developerId]')
-    .description('Update a developer (name, email, groups); use --developer-id like dev add')
+    .description('Patch name/email/groups (admin); only given flags change')
     .option('--developer-id <id>', 'Developer ID (same as dev add)')
     .option('--name <name>', 'Display name')
     .option('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, developer)')
+    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, developer, docker)')
+    .addHelpText('after', DEV_UPDATE_HELP_AFTER)
     .action(async(developerId, options) => {
       try {
         await handleDevUpdate(developerId, options);
@@ -258,10 +310,12 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('pin [developerId]')
-    .description('Create or regenerate one-time PIN for onboarding (admin; show once to developer)')
-    .action(async(developerId) => {
+    .description('One-time onboarding PIN for dev init (admin)')
+    .option('--hosts-ip <ip>', 'Builder Server LAN IPv4 to embed in the hosts-file init command (optional)')
+    .addHelpText('after', DEV_PIN_HELP_AFTER)
+    .action(async(developerId, options) => {
       try {
-        await handleDevPin(developerId);
+        await handleDevPin(developerId, options);
       } catch (error) {
         handleCommandError(error, 'dev pin');
         process.exit(1);
@@ -270,7 +324,8 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('delete <developerId>')
-    .description('Remove a developer (remote Builder Server only; admin)')
+    .description('Remove developer from server (admin)')
+    .addHelpText('after', DEV_DELETE_HELP_AFTER)
     .action(async(developerId) => {
       try {
         await handleDevDelete(developerId);
@@ -282,7 +337,8 @@ function setupDevUpdatePinDeleteCommands(dev) {
 
   dev
     .command('down')
-    .description('Stop Mutagen sync sessions for this developer (and optionally app containers)')
+    .description('Stop Mutagen sync; --apps also stops app containers')
+    .addHelpText('after', DEV_DOWN_HELP_AFTER)
     .option('--apps', 'Also stop running app containers for this developer')
     .action(async(options) => {
       try {
@@ -311,7 +367,8 @@ function setupDevUserCommands(dev) {
 function setupDevCommands(program) {
   const dev = program
     .command('dev')
-    .description('Developer configuration and isolation');
+    .description('Local dev config, Builder onboarding, remote admin, Mutagen/sync')
+    .addHelpText('after', DEV_GROUP_HELP_AFTER);
 
   setupDevConfigCommands(dev);
   setupDevInitCommand(dev);

package/lib/cli/setup-environment.js

@@ -29,9 +29,15 @@ Examples:
   $ aifabrix env deploy tst --preset m
   $ aifabrix env deploy dev --config ./env-config.json --no-poll`;
 
+  const ENV_GROUP_HELP_AFTER = `
+Subcommands:
+  deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
+`;
+
   const env = program
     .command('env')
-    .description('Deploy and manage Miso Controller environments (dev, tst, pro, miso)');
+    .description('Miso Controller environments (primary: env deploy <env>)')
+    .addHelpText('after', ENV_GROUP_HELP_AFTER);
 
   env
     .command('deploy <env>')