@aifabrix/builder 2.43.0 → 2.44.1

package/lib/cli/setup-app.test-commands.js

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview CLI test/install/lint command setup (builder app + external integration dispatch).
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
+const { TEST_HELP_AFTER, TEST_E2E_HELP_AFTER } = require('./setup-app.help');
+
+function setupTestCommand(program) {
+  program.command('test <app>')
+    .description('Tests: builder in container; external = local validation')
+    .option('-e, --env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
+    .option('-v, --verbose', 'Verbose output')
+    .option('-d, --debug', 'Write debug log to integration/<systemKey>/logs/ (external only)')
+    .option(
+      '--sync',
+      'Not supported for this command (local validation only). Use aifabrix upload <systemKey> or dataplane test commands with --sync.'
+    )
+    .addHelpText('after', TEST_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
+      try {
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (options.sync === true) {
+          throw new Error(
+            'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
+              'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
+          );
+        }
+        if (appType && appType.baseDir === 'integration') {
+          const test = require('../external-system/test');
+          const externalOpts = {
+            ...options,
+            // Keep help default but don't override auth/env behavior unless user explicitly set it.
+            env: envExplicit ? options.env : undefined
+          };
+          const results = await test.testExternalSystem(appName, externalOpts);
+          test.displayTestResults(results, options.verbose, appName);
+          if (!results.valid) process.exit(1);
+          return;
+        }
+        const { runAppTest } = require('../commands/app-test');
+        await runAppTest(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'test');
+        process.exit(1);
+      }
+    });
+}
+
+async function runTestE2ECommand(appName, options) {
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (options.sync === true && appType && appType.baseDir === 'builder') {
+    throw new Error(
+      'Option --sync applies only to external integration E2E (integration/<systemKey>/). ' +
+        'Remove --sync for builder app E2E, or use aifabrix upload from the integration folder first.'
+    );
+  }
+  if (appType && appType.baseDir === 'integration') {
+    const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+    const { success, results } = await runTestE2EForExternalSystem(appName, {
+      env: options.env,
+      debug: options.debug,
+      verbose: options.verbose,
+      async: options.async !== false,
+      sync: options.sync === true
+    });
+    const { displayIntegrationTestResults } = require('../utils/external-system-display');
+    const datasourceResults = results.map(r => ({
+      key: r.key,
+      success: r.success,
+      error: r.error,
+      skipped: false,
+      datasourceTestRun: r.datasourceTestRun
+    }));
+    displayIntegrationTestResults(
+      {
+        systemKey: appName,
+        success,
+        datasourceResults
+      },
+      options.verbose,
+      { debug: options.debug, runType: 'e2e' }
+    );
+    const { computeSystemExitCodeFromDatasourceRows } = require('../utils/datasource-test-run-exit');
+    const exitCode = computeSystemExitCodeFromDatasourceRows(datasourceResults, {
+      warningsAsErrors: options.warningsAsErrors === true,
+      requireCert: options.requireCert === true
+    });
+    if (exitCode !== 0) process.exit(exitCode);
+    if (cliOptsSkipCertSync(options)) return;
+    const { trySyncCertificationFromDataplaneForExternalApp } = require('../certification/sync-after-external-command');
+    await trySyncCertificationFromDataplaneForExternalApp(appName, 'test-e2e');
+    return;
+  }
+  const { runAppTestE2e } = require('../commands/app-test');
+  await runAppTestE2e(appName, { env: options.env });
+}
+
+function setupInstallCommand(program) {
+  program.command('install <app>')
+    .description('Install deps in container (builder apps only)')
+    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .action(async(appName, options) => {
+      try {
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (appType && appType.baseDir === 'integration') {
+          logger.log(
+            chalk.gray('Install is for builder applications only. Use aifabrix shell <app> to run commands in external setups.')
+          );
+          return;
+        }
+        const { runAppInstall } = require('../commands/app-install');
+        await runAppInstall(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'install');
+        process.exit(1);
+      }
+    });
+}
+
+function setupTestE2eCommand(program) {
+  program.command('test-e2e <app>')
+    .description('E2E: builder in container; external = all datasources via dataplane')
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
+    .option('-v, --verbose', 'Show detailed step output and poll progress')
+    .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
+    .option(
+      '--sync',
+      'Publish local system and datasource files to the dataplane before running E2E (same as aifabrix upload <systemKey>; external integration only)'
+    )
+    .option('--warnings-as-errors', 'Treat aggregate warn as failure (exit 1)')
+    .option('--require-cert', 'Require certification passed on every datasource (exit 2 if not)')
+    .option(
+      '--no-cert-sync',
+      'Skip updating the system file certification block from the dataplane after a successful run'
+    )
+    .addHelpText('after', TEST_E2E_HELP_AFTER)
+    .action(async(appName, options, cmd) => {
+      try {
+        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+        const externalOpts = {
+          ...options,
+          env: envExplicit ? options.env : undefined,
+          async: true // system-level command surface omits --no-async; always poll for completeness
+        };
+        await runTestE2ECommand(appName, externalOpts);
+      } catch (error) {
+        handleCommandError(error, 'test-e2e');
+        process.exit(1);
+      }
+    });
+}
+
+function setupLintCommand(program) {
+  program.command('lint <app>')
+    .description('Lint in container (builder apps only)')
+    .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
+    .action(async(appName, options) => {
+      try {
+        const pathsUtil = require('../utils/paths');
+        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+        if (appType && appType.baseDir === 'integration') {
+          logger.log(chalk.gray('lint is for builder applications only. Use aifabrix shell <app> then make lint or pnpm lint.'));
+          return;
+        }
+        const { runAppLint } = require('../commands/app-test');
+        await runAppLint(appName, { env: options.env });
+      } catch (error) {
+        handleCommandError(error, 'lint');
+        process.exit(1);
+      }
+    });
+}
+
+function setupInstallTestE2eLintCommands(program) {
+  setupInstallCommand(program);
+  setupTestCommand(program);
+  setupTestE2eCommand(program);
+  setupLintCommand(program);
+}
+
+module.exports = {
+  setupInstallTestE2eLintCommands
+};
+

package/lib/cli/setup-auth.js

@@ -14,9 +14,22 @@ const { handleLogout } = require('../commands/logout');
 const { handleAuthStatus } = require('../commands/auth-status');
 const { handleAuthConfig } = require('../commands/auth-config');
 
+const LOGIN_HELP_AFTER = `
+Examples:
+  $ aifabrix login
+  $ aifabrix login -m credentials -a myapp -e dev
+`;
+
+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.
+Subcommand: auth status [--validate] for CI/scripts.
+`;
+
 function setupLoginCommand(program) {
   program.command('login')
-    .description('Authenticate with Miso Controller')
+    .description('Sign in to Miso Controller (device or credentials flow)')
+    .addHelpText('after', LOGIN_HELP_AFTER)
     .option('-c, --controller <url>', 'Controller URL (default: from config or developer ID, e.g. http://localhost:3000)')
     .option('-m, --method <method>', 'Authentication method (device|credentials)', 'device')
     .option('-a, --app <app>', 'Application name (required for credentials method, reads from secrets.local.yaml)')
@@ -29,7 +42,7 @@ function setupLoginCommand(program) {
       try {
         await handleLogin(options);
       } catch (error) {
-        logger.error(chalk.red('\n❌ Login failed:'), error.message);
+        logger.error(chalk.red('\n✖ Login failed:'), error.message);
         process.exit(1);
       }
     });
@@ -37,7 +50,7 @@ function setupLoginCommand(program) {
 
 function setupLogoutCommand(program) {
   program.command('logout')
-    .description('Clear authentication tokens')
+    .description('Clear stored tokens (optional filter by controller/env/app)')
     .option('-c, --controller <url>', 'Clear device tokens for specific controller')
     .option('-e, --environment <env>', 'Clear client tokens for specific environment')
     .option('-a, --app <app>', 'Clear client tokens for specific app (requires --environment)')
@@ -61,7 +74,8 @@ function setupAuthSubcommands(program) {
     }
   };
   const auth = program.command('auth')
-    .description('Authentication status and config (controller, environment)')
+    .description('Show auth status or set default controller/environment')
+    .addHelpText('after', AUTH_HELP_AFTER)
     .option('--set-controller <url>', 'Set default controller URL in config')
     .option('--set-environment <env>', 'Set default environment in config')
     .action(async(options) => {
@@ -82,7 +96,7 @@ function setupAuthSubcommands(program) {
       }
     });
   auth.command('status')
-    .description('Display authentication status for current controller and environment')
+    .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)')
     .action(authStatusHandler);
 }

package/lib/cli/setup-credential-deployment.js

@@ -15,10 +15,22 @@ const { runCredentialEnv } = require('../commands/credential-env');
 const { runCredentialPush } = require('../commands/credential-push');
 const { runDeploymentList } = require('../commands/deployment-list');
 
+const CREDENTIAL_HELP_AFTER = `
+Subcommands:
+  env <systemKey>   Prompt for KV_* values → integration/<key>/.env
+  push <systemKey>  Upload secrets from .env to Dataplane
+  list               List credentials (pagination: --page-size)
+`;
+
+const DEPLOYMENT_HELP_AFTER = `
+Subcommand:
+  list   Recent deployments for the current environment
+`;
+
 function setupCredentialEnvAndPush(credential) {
   credential
-    .command('env <system-key>')
-    .description('Prompt for KV_* credential values and write integration/<system-key>/.env')
+    .command('env <systemKey>')
+    .description('Interactive KV_* prompts → integration/<key>/.env')
     .action(async(systemKey, _options) => {
       try {
         await runCredentialEnv(systemKey);
@@ -29,8 +41,8 @@ function setupCredentialEnvAndPush(credential) {
       }
     });
   credential
-    .command('push <system-key>')
-    .description('Push credential secrets from .env to Dataplane (KV_* vars)')
+    .command('push <systemKey>')
+    .description('Push KV_* secrets from .env to Dataplane')
     .action(async(systemKey, _options) => {
       try {
         await runCredentialPush(systemKey);
@@ -49,11 +61,12 @@ function setupCredentialEnvAndPush(credential) {
 function setupCredentialDeploymentCommands(program) {
   const credential = program
     .command('credential')
-    .description('Manage credentials');
+    .description('Dataplane credentials: env, push, list')
+    .addHelpText('after', CREDENTIAL_HELP_AFTER);
   setupCredentialEnvAndPush(credential);
   credential
     .command('list')
-    .description('Get credentials from Dataplane')
+    .description('List credentials from Dataplane')
     .option('--active-only', 'List only active credentials')
     .option('--page-size <n>', 'Items per page', '50')
     .action(async(options) => {
@@ -72,11 +85,12 @@ function setupCredentialDeploymentCommands(program) {
 
   const deployment = program
     .command('deployment')
-    .description('List deployments');
+    .description('Controller deployments (list)')
+    .addHelpText('after', DEPLOYMENT_HELP_AFTER);
 
   deployment
     .command('list')
-    .description('List last N deployments for current environment (default pageSize=50)')
+    .description('List recent deployments for current environment')
     .option('--controller <url>', 'Controller URL (default: from config)')
     .option('--environment <env>', 'Environment key (default: from config)')
     .option('--page-size <n>', 'Items per page', '50')

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 };