@aifabrix/builder 2.44.5 → 2.44.6

package/lib/cli/infra-guided.js

@@ -0,0 +1,445 @@
+/**
+ * @fileoverview Guided (non-verbose) UX for infra/platform commands.
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const config = require('../core/config');
+const devConfig = require('../utils/dev-config');
+const pathsUtil = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { withMutedLogger } = require('../utils/with-muted-logger');
+const { formatBlockingError, formatProgress, formatSuccessLine, successGlyph } = require('../utils/cli-test-layout-chalk');
+const { computePublicUrlBaseString } = require('../utils/url-declarative-public-base');
+const { joinUrlPath, normalizeFrontDoorPatternForHealth } = require('../utils/health-check-url');
+const ora = require('ora');
+const infra = require('../infrastructure');
+const { execWithDockerEnv } = require('../utils/docker-exec');
+const { getLogLevel, passesLevelFilter } = require('../commands/app-logs');
+const { handleLogin } = require('../commands/login');
+const healthCheck = require('../utils/health-check');
+const { prepareUrlsLocalRegistryForUpPlatform } = require('../commands/up-common');
+const { assertDevInfraUp } = require('../commands/dev-infra-gate');
+
+const SEPARATOR = '────────────────────────────────────────';
+
+function title(text) {
+  return chalk.bold(text);
+}
+
+function shouldUseSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+function startSpinner(text) {
+  if (!shouldUseSpinner()) {
+    logger.log(formatProgress(text));
+    return null;
+  }
+  return ora({ text, spinner: 'dots' }).start();
+}
+
+function stopSpinnerSuccess(spinner, text) {
+  if (!spinner) {
+    logger.log(formatSuccessLine(text));
+    return;
+  }
+  spinner.succeed(text);
+}
+
+async function getRunningContainerNameForApp(appName) {
+  const apps = await infra.getAppStatus();
+  const hit = (apps || []).find(a => a && a.name === appName && a.container);
+  return hit ? hit.container : null;
+}
+
+async function hasErrorLogs(appName, opts = {}) {
+  const tailLines = Number.isFinite(opts.tailLines) ? opts.tailLines : 200;
+  const container = await getRunningContainerNameForApp(appName);
+  if (!container) return false;
+  const { stdout } = await execWithDockerEnv(`docker logs --tail ${tailLines} ${container}`);
+  const lines = String(stdout || '').split('\n');
+  return lines.some(line => passesLevelFilter(getLogLevel(line), 'error'));
+}
+
+async function validateAppErrorLogs(appNames) {
+  const names = Array.isArray(appNames) ? appNames : [];
+  const results = await Promise.all(
+    names.map(async(name) => {
+      try {
+        const hasErrors = await hasErrorLogs(name, { tailLines: 300 });
+        return { name, hasErrors };
+      } catch {
+        return { name, hasErrors: false };
+      }
+    })
+  );
+  const bad = results.filter(r => r && r.hasErrors);
+  if (bad.length === 0) return;
+
+  logger.log(chalk.yellow('⚠ Some services reported error logs'));
+  for (const r of bad) {
+    logger.log(chalk.gray(`  Run: aifabrix logs ${r.name} -l error`));
+  }
+  logger.log('');
+}
+
+async function waitForAppReady(appName, opts = {}) {
+  const timeoutSeconds = Number.isFinite(opts.timeoutSeconds) ? opts.timeoutSeconds : 90;
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  const appConfig = loadConfigFile(configPath) || {};
+
+  const apps = await infra.getAppStatus();
+  const hit = (apps || []).find(a => a && a.name === appName && typeof a.url === 'string');
+  const portMatch = hit && hit.url ? hit.url.match(/:(\d+)$/) : null;
+  const hostPort = portMatch ? parseInt(portMatch[1], 10) : null;
+  if (!hostPort) {
+    throw new Error(`Could not determine host port for ${appName}`);
+  }
+
+  const userCfg = await config.getConfig();
+  const healthRunOpts = { profile: 'docker' };
+  if (userCfg && userCfg.traefik === true) {
+    healthRunOpts.traefikEnabled = true;
+  }
+  await healthCheck.waitForHealthCheck(appName, timeoutSeconds, hostPort, appConfig, false, healthRunOpts);
+}
+
+function resolveInfraHost(remoteServer) {
+  const raw = String(remoteServer || '').trim().replace(/\/+$/, '');
+  if (!raw) return 'localhost';
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`;
+    const u = new URL(withScheme);
+    return u.hostname || 'localhost';
+  } catch {
+    // Fallback for non-URL strings.
+    return raw.replace(/^https?:\/\//i, '').split('/')[0].split(':')[0] || 'localhost';
+  }
+}
+
+async function computeAppBaseUrl(appName) {
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
+  const variables = loadConfigFile(configPath) || {};
+  const basePort = Number(variables.port || 3000);
+  const developerIdRaw = await config.getDeveloperId();
+  const developerIdNum = typeof developerIdRaw === 'string' ? parseInt(developerIdRaw, 10) : developerIdRaw;
+  const userCfg = await config.getConfig();
+  const remoteServer = await config.getRemoteServer();
+  const infraTlsEnabled = Boolean(userCfg && userCfg.tlsEnabled);
+
+  const fd = variables.frontDoorRouting || null;
+  const frontDoorEnabled = Boolean(fd && fd.enabled === true);
+  const traefikOn = Boolean(userCfg && userCfg.traefik);
+  const pathActive = Boolean(traefikOn && frontDoorEnabled);
+
+  const publicBase = computePublicUrlBaseString({
+    traefik: traefikOn,
+    pathActive,
+    hostTemplate: fd ? fd.host : null,
+    tls: fd ? fd.tls : true,
+    developerIdRaw,
+    remoteServer,
+    // These guided bootstrap commands start services via Docker Compose, so we want the
+    // docker-published host port (no workstation +10 offset).
+    profile: 'docker',
+    listenPort: basePort,
+    developerIdNum,
+    infraTlsEnabled
+  });
+
+  if (pathActive) {
+    const mount = normalizeFrontDoorPatternForHealth(fd.pattern);
+    return joinUrlPath(publicBase, mount);
+  }
+
+  // No Traefik front-door routing: publicBase already includes correct scheme/host/port (localhost or remote-server).
+  return String(publicBase).replace(/\/+$/, '');
+}
+
+function logSection(label, value) {
+  logger.log(title(label));
+  logger.log(`  ${value}`);
+  logger.log('');
+}
+
+function logFooterStart(label) {
+  logger.log('');
+  logger.log(SEPARATOR);
+  logger.log(title(label));
+  logger.log(SEPARATOR);
+  logger.log('');
+}
+
+function logFooterEnd() {
+  logger.log(SEPARATOR);
+}
+
+async function logPlatformReadyFooter() {
+  const [controllerUrl, dataplaneUrl, keycloakUrl] = await Promise.all([
+    resolveControllerUrl(),
+    computeAppBaseUrl('dataplane'),
+    computeAppBaseUrl('keycloak')
+  ]);
+  const cfg = await config.getConfig();
+  const env = (cfg && cfg.environment) ? cfg.environment : 'dev';
+
+  logFooterStart('Platform Ready');
+  logSection('Environment', env);
+  logSection('Miso Controller', controllerUrl);
+  logSection('Dataplane (DEV)', dataplaneUrl);
+  logSection('Keycloak', keycloakUrl);
+  logSection('API Documentation', `${dataplaneUrl}/api/docs`);
+  logSection('Knowledge Base', 'https://docs.aifabrix.ai');
+  logSection('Getting Started', 'https://docs.aifabrix.ai/get-started');
+  logFooterEnd();
+}
+
+async function logMisoReadyFooter() {
+  const [controllerUrl, keycloakUrl] = await Promise.all([
+    resolveControllerUrl(),
+    computeAppBaseUrl('keycloak')
+  ]);
+  logFooterStart('Miso Ready');
+  logSection('Miso Controller', controllerUrl);
+  logSection('Keycloak', keycloakUrl);
+  logFooterEnd();
+}
+
+async function logDataplaneReadyFooter() {
+  const dataplaneUrl = await computeAppBaseUrl('dataplane');
+  const cfg = await config.getConfig();
+  const env = (cfg && cfg.environment) ? cfg.environment : 'dev';
+  logFooterStart('Dataplane Ready');
+  logSection('Environment', env);
+  logSection('Dataplane (DEV)', dataplaneUrl);
+  logSection('API Documentation', `${dataplaneUrl}/api/docs`);
+  logFooterEnd();
+}
+
+async function getInfraHostAndPorts() {
+  const developerId = await config.getDeveloperId();
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const ports = devConfig.getDevPorts(idNum);
+  const remoteServer = await config.getRemoteServer();
+  const host = resolveInfraHost(remoteServer);
+  return { idNum, ports, host };
+}
+
+async function runGuidedUpInfra(options, runUpInfraCommand) {
+  logger.log('');
+  logger.log(title('AI Fabrix Infrastructure Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+  const spin = startSpinner('Starting infrastructure services...');
+  await withMutedLogger(() => runUpInfraCommand(options), {
+    allow: (msg) => {
+      if (typeof msg !== 'string') return false;
+      return (
+        msg.includes('✔ Developer ID set to') ||
+        msg.includes('✔ Traefik enabled and saved to config') ||
+        msg.includes('✔ Traefik disabled and saved to config') ||
+        msg.includes('✔ pgAdmin enabled and saved to config') ||
+        msg.includes('✔ pgAdmin disabled and saved to config') ||
+        msg.includes('✔ Redis Commander enabled and saved to config') ||
+        msg.includes('✔ Redis Commander disabled and saved to config')
+      );
+    }
+  });
+  stopSpinnerSuccess(spin, 'Infrastructure ready');
+
+  const [{ idNum, ports, host }, cfg] = await Promise.all([
+    getInfraHostAndPorts(),
+    config.getConfig()
+  ]);
+
+  logFooterStart('Infra Ready');
+  logSection('Developer', `dev${String(idNum).padStart(2, '0')} (id: ${idNum})`);
+  logSection('Postgres', `${host}:${ports.postgres}`);
+  logSection('Redis', `${host}:${ports.redis}`);
+  if (cfg.pgadmin !== false) logSection('pgAdmin', `http://${host}:${ports.pgadmin}`);
+  if (cfg.redisCommander !== false) logSection('Redis Commander', `http://${host}:${ports.redisCommander}`);
+  if (cfg.traefik) logSection('Traefik', `http://${host}:${ports.traefikHttp}`);
+  if (cfg.tlsEnabled === true) logSection('TLS mode', 'on');
+  logFooterEnd();
+}
+
+async function runGuidedUpMiso(options, handleUpMiso) {
+  logger.log('');
+  logger.log(title('AI Fabrix Platform Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+  const kcSpin = startSpinner('Starting Keycloak...');
+  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+  logger.log('');
+  const mcSpin = startSpinner('Starting Miso Controller...');
+  await waitForAppReady('miso-controller', { timeoutSeconds: 120 });
+  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
+  await logMisoReadyFooter();
+  await validateAppErrorLogs(['miso-controller']);
+}
+
+async function runGuidedUpDataplane(options, handleUpDataplane) {
+  logger.log('');
+  logger.log(title('AI Fabrix Dataplane Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+  // Infra must be checked before auth: device login talks to the controller, which needs
+  // Postgres/Redis when the controller runs locally — a down infra looks like "network error".
+  const infraSpin = startSpinner('Checking infrastructure...');
+  try {
+    await assertDevInfraUp({ quietSuccess: true });
+    stopSpinnerSuccess(infraSpin, 'Infrastructure is up');
+  } catch (infraErr) {
+    // Match up-miso: one error block from handleCommandError only (no spinner.fail / extra hints).
+    if (infraSpin) infraSpin.stop();
+    throw infraErr;
+  }
+  // Avoid an outer long-running spinner here: up-dataplane has multiple internal
+  // phases and may print some output. An outer spinner causes "spinner over spinner"
+  // rendering artifacts. Instead, do the same single auth step as up-platform, then
+  // show one spinner for the dataplane install/run phase.
+  await runGuidedAuthStep(handleLogin);
+
+  logger.log('');
+  const dpSpin = startSpinner('Starting Dataplane...');
+  await withMutedLogger(() =>
+    handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
+  );
+  stopSpinnerSuccess(dpSpin, 'Dataplane ready');
+  await validateAppErrorLogs(['dataplane']);
+  await logDataplaneReadyFooter();
+}
+
+/**
+ * Guided-mode summary after `up-platform --force` (printed under the platform header).
+ * @param {{ deviceCleared: number, clientCleared: number, environment: string, defaultControllerUrl: string }} forceSummary
+ * @param {string[]} cleanedApps
+ */
+function logUpPlatformForceCleanSummary(forceSummary, cleanedApps) {
+  const check = successGlyph();
+  logger.log(chalk.bold('Clean installation files'));
+  logger.log(
+    chalk.gray(
+      ` ${check} Cleared ${forceSummary.deviceCleared} device token(s) and ${forceSummary.clientCleared} client token(s)`
+    )
+  );
+  logger.log(chalk.gray(` ${check} Environment set to ${forceSummary.environment}`));
+  logger.log(
+    chalk.gray(
+      ` ${check} Default controller set to ${forceSummary.defaultControllerUrl} (run aifabrix login after platform is up)`
+    )
+  );
+  for (const appName of cleanedApps || []) {
+    logger.log(chalk.gray(` ${check} Cleaned builder/${appName}`));
+  }
+  logger.log('');
+}
+
+function logGuidedPlatformSetupHeader() {
+  logger.log('');
+  logger.log(title('AI Fabrix Platform Setup'));
+  logger.log(SEPARATOR);
+  logger.log('');
+}
+
+async function runGuidedAuthStep(handleLogin) {
+  const spin = startSpinner('Authenticating...');
+  try {
+    const controllerUrl = await resolveControllerUrl();
+    await handleLogin({ method: 'device', controller: controllerUrl, environment: 'dev', compact: true });
+  } catch (authErr) {
+    if (spin) spin.fail('Authentication failed');
+    logger.error(formatBlockingError('Authentication failed'));
+    logger.log(chalk.gray('\nRun:\n  af login\n\nThen retry:\n  af up-platform\n'));
+    throw authErr;
+  }
+  // Compact device-login already prints a success line; don't duplicate it.
+  if (spin) spin.stop();
+}
+
+async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, handleLogin, forceCleanSummary = null) {
+  logGuidedPlatformSetupHeader();
+  if (forceCleanSummary && forceCleanSummary.forceSummary) {
+    logUpPlatformForceCleanSummary(forceCleanSummary.forceSummary, forceCleanSummary.cleanedApps);
+  }
+
+  await withMutedLogger(() => prepareUrlsLocalRegistryForUpPlatform());
+
+  const kcSpin = startSpinner('Starting Keycloak...');
+  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+  logger.log('');
+
+  const mcSpin = startSpinner('Starting Miso Controller...');
+  await waitForAppReady('miso-controller', { timeoutSeconds: 120 });
+  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
+  logger.log('');
+
+  await runGuidedAuthStep(handleLogin);
+
+  logger.log('');
+  const dpSpin = startSpinner('Starting Dataplane...');
+  await withMutedLogger(() =>
+    handleUpDataplane({ ...options, platformInstall: true, skipInfraCheck: true })
+  );
+  stopSpinnerSuccess(dpSpin, 'Dataplane ready');
+  await validateAppErrorLogs(['miso-controller', 'dataplane']);
+  await logPlatformReadyFooter();
+}
+
+function logStoppedServices(cfg) {
+  logger.log(title('Stopped'));
+  logger.log('  postgres');
+  logger.log('  redis');
+  if (cfg.pgadmin !== false) logger.log('  pgadmin');
+  if (cfg.redisCommander !== false) logger.log('  redis-commander');
+  if (cfg.traefik) logger.log('  traefik');
+  logger.log('');
+}
+
+async function runGuidedDownInfra(appName, options, infra, appLib) {
+  logger.log('');
+  logger.log(title('AI Fabrix Shutdown'));
+  logger.log(SEPARATOR);
+  logger.log('');
+
+  const spin = startSpinner('Stopping infrastructure...');
+  await withMutedLogger(async() => {
+    if (typeof appName === 'string' && appName.trim().length > 0) {
+      await appLib.downApp(appName, { volumes: !!options.volumes });
+      return;
+    }
+    if (options.volumes) await infra.stopInfraWithVolumes();
+    else await infra.stopInfra();
+  });
+  stopSpinnerSuccess(spin, 'Infrastructure stopped');
+
+  const developerId = await config.getDeveloperId();
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const cfg = await config.getConfig();
+
+  logFooterStart('Stopped');
+  logSection('Developer', `dev${String(idNum).padStart(2, '0')} (id: ${idNum})`);
+  logStoppedServices(cfg);
+  if (options.volumes) {
+    logger.log(chalk.yellow('⚠ Volumes removed: all local data deleted'));
+    logger.log('');
+  }
+  logFooterEnd();
+}
+
+module.exports = {
+  runGuidedUpInfra,
+  runGuidedUpMiso,
+  runGuidedUpDataplane,
+  runGuidedUpPlatform,
+  runGuidedDownInfra
+};
+

package/lib/cli/setup-app.js

@@ -31,6 +31,19 @@ Example:
   $ aifabrix push myapp -t v1.0.0
 `;
 
+const LOGS_HELP_AFTER = `
+Examples:
+  $ aifabrix logs miso-controller -l error
+  $ aifabrix logs miso-controller -f
+  $ aifabrix logs dataplane -l warn
+  $ aifabrix logs dataplane -f -t 100
+  $ aifabrix logs keycloak -f -t 0
+
+Notes:
+  - Platform apps use names such as miso-controller, dataplane, keycloak (see aifabrix run).
+  - Use -t 0 (--tail 0) for the full buffered log; default is 100 lines.
+`;
+
 /**
  * Normalize options for external system creation
  * @param {Object} options - Raw CLI options
@@ -188,11 +201,12 @@ See integration/hubspot-test/wizard-hubspot-e2e.yaml for an example.`;
 
 function registerRunCommand(program) {
   const runHelp = `
-In dev: use --reload for sync and mount (requires remote server with Mutagen, or local Docker).
+In dev: use --reload for live code in the container. Before start, the CLI prints a "Reload (dev)" section: direct bind mount when the Docker engine is on this machine, or Mutagen when the engine is remote.
 Examples:
   $ aifabrix run myapp
   $ aifabrix run myapp --env tst
   $ aifabrix run myapp --tag v1.0.0
+  $ aifabrix run myapp --base
   $ aifabrix run myapp --reload`;
   program.command('run <app>')
     .description('Run app locally or on remote Docker host')
@@ -200,7 +214,8 @@ Examples:
     .option('-d, --debug', 'Enable debug output with detailed container information')
     .option('-t, --tag <tag>', 'Image tag to run (e.g. v1.0.0); overrides application.yaml image.tag')
     .option('-e, --env <env>', 'Environment: dev (default), tst, or pro', 'dev')
-    .option('--reload', 'In dev: use sync and mount (requires remote server; Mutagen or local Docker)')
+    .option('--base', 'Use manifest base image only (skip local developer-scoped tag preference)')
+    .option('--reload', 'In dev: mount workspace into container (Mutagen only if docker-endpoint is a remote host)')
     .addHelpText('after', runHelp)
     .action(async(appName, options) => {
       try {
@@ -219,6 +234,7 @@ function setupBuildRunLogsDownCommands(program) {
     .option('-f, --force-template', 'Force rebuild from template')
     .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
     .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
+    .option('--base', 'Also tag the manifest base image name (after developer-scoped build when developer id > 0)')
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);
@@ -236,6 +252,7 @@ function setupBuildRunLogsDownCommands(program) {
     .option('-f', 'Follow log stream')
     .option('-t, --tail <lines>', 'Number of lines (default: 100); 0 = full list', '100')
     .option('-l, --level <level>', 'Show only logs at this level or above (debug|info|warn|error)')
+    .addHelpText('after', LOGS_HELP_AFTER)
     .action(async(appName, options) => {
       try {
         const { runAppLogs } = require('../commands/app-logs');
@@ -328,6 +345,7 @@ function setupPushDeployDockerfileCommands(program) {
     .option('--local', 'Send manifest to controller then run app locally (app: same as aifabrix run <app>; external: restart dataplane)')
     .option('--client-id <id>', 'Client ID (overrides config)')
     .option('--client-secret <secret>', 'Client Secret (overrides config)')
+    .option('--repository-url <url>', 'Repository URL for pipeline validation (default: application.yaml repository.repositoryUrl, else https://github.com/aifabrix/<appKey>)')
     .option('--poll', 'Poll for deployment status', true)
     .option('--no-poll', 'Do not poll for status')
     .option('--probe', 'After external deploy, run dataplane runtime checks (validation/run); slower')

package/lib/cli/setup-auth.js

@@ -23,6 +23,9 @@ Examples:
 const AUTH_HELP_AFTER = `
 Without options: show auth status (same as: aifabrix auth status).
 With --set-controller or --set-environment: write defaults to config.yaml.
+Aliases:
+  aifabrix auth set-controller <url>
+  aifabrix auth set-environment <env>
 Subcommand: auth status [--validate] for CI/scripts.
 `;
 
@@ -95,6 +98,29 @@ function setupAuthSubcommands(program) {
         process.exit(1);
       }
     });
+
+  auth.command('set-controller <url>')
+    .description('Set default controller URL in config (alias for auth --set-controller)')
+    .action(async(url) => {
+      try {
+        await handleAuthConfig({ setController: url });
+      } catch (error) {
+        handleCommandError(error, 'auth set-controller');
+        process.exit(1);
+      }
+    });
+
+  auth.command('set-environment <env>')
+    .description('Set default environment in config (alias for auth --set-environment)')
+    .action(async(env) => {
+      try {
+        await handleAuthConfig({ setEnvironment: env });
+      } catch (error) {
+        handleCommandError(error, 'auth set-environment');
+        process.exit(1);
+      }
+    });
+
   auth.command('status')
     .description('Show tokens/session for current controller and environment')
     .option('--validate', 'Exit with code 1 when not authenticated (for scripted use, e.g. manual test setup)')

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

@@ -1,5 +1,5 @@
 /**
- * Dev subcommands: set-home, set-work, print-home, print-work, set-format.
+ * Dev subcommands: set-home, set-work, print-home, print-work, shell-env, set-format.
  *
  * @fileoverview Path and format CLI registration for `aifabrix dev`
  * @author AI Fabrix Team
@@ -10,18 +10,35 @@
 const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 
 const chalk = require('chalk');
+const path = require('path');
 const config = require('../core/config');
 const logger = require('../utils/logger');
 const paths = require('../utils/paths');
-const { registerAifabrixShellEnvFromConfig } = require('../utils/register-aifabrix-shell-env');
+const {
+  registerAifabrixShellEnvFromConfig,
+  buildShellEnvExportsFromConfig
+} = 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.')
+      chalk.gray('  User/shell environment updated. New terminals pick up AIFABRIX_HOME / AIFABRIX_WORK.')
     );
+    if (process.platform !== 'win32') {
+      logger.log(
+        chalk.gray('  This terminal: ') +
+          chalk.cyan('eval "$(aifabrix dev shell-env)"') +
+          chalk.gray('  (or source the aifabrix-shell-env.sh next to config.yaml).')
+      );
+    } else {
+      logger.log(
+        chalk.gray('  This PowerShell session: ') +
+          chalk.cyan('aifabrix dev shell-env') +
+          chalk.gray(' then run the printed lines.')
+      );
+    }
   } catch (regErr) {
     throw new Error(`Config saved but environment registration failed: ${regErr.message}`);
   }
@@ -92,6 +109,36 @@ function addPrintHomeWorkCommands(dev) {
         process.exit(1);
       }
     });
+
+  dev
+    .command('shell-env')
+    .description(
+      'Print export lines for AIFABRIX_HOME / AIFABRIX_WORK (stdout only). POSIX: eval "$(aifabrix dev shell-env)"'
+    )
+    .action(async() => {
+      try {
+        if (process.platform === 'win32') {
+          const cfg = await config.getConfig();
+          const home = (cfg['aifabrix-home'] && String(cfg['aifabrix-home']).trim())
+            ? paths.resolveAifabrixHomeLikePath(String(cfg['aifabrix-home']).trim())
+            : null;
+          const work = (cfg['aifabrix-work'] && String(cfg['aifabrix-work']).trim())
+            ? path.resolve(String(cfg['aifabrix-work']).trim())
+            : null;
+          const esc = (s) => String(s).replace(/'/g, '\'\'');
+          const lines = ['# Paste into PowerShell for this session only.'];
+          if (home) lines.push(`$env:AIFABRIX_HOME = '${esc(home)}'`);
+          if (work) lines.push(`$env:AIFABRIX_WORK = '${esc(work)}'`);
+          process.stdout.write(`${lines.join('\n')}\n`);
+          return;
+        }
+        const body = await buildShellEnvExportsFromConfig(config.getConfig);
+        process.stdout.write(body);
+      } catch (error) {
+        handleCommandError(error, 'dev shell-env');
+        process.exit(1);
+      }
+    });
 }
 
 function addSetFormatCommand(dev, handleSetFormat) {