@aifabrix/builder 2.49.2 → 2.51.0

package/lib/cli/setup-certification-commands.js

@@ -20,7 +20,7 @@ function setupVerifyOperationsCommand(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('-v, --verbose', 'Readiness breakdown and verification step checklist')
     .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/')
-    .option('--no-sync', 'Skip publishing local integration files before dataplane steps')
+    .option('--no-publish', 'Skip publishing local integration files before dataplane steps')
     .option(
       '--force',
       'With default sync, pass force to upload (same as aifabrix upload --force)'
@@ -39,7 +39,7 @@ function setupVerifyTrustCommand(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('-v, --verbose', 'Per-datasource breakdown')
     .option('-d, --debug', 'Write debug log under integration/<systemKey>/logs/')
-    .option('--no-sync', 'Skip publishing local integration files before validate')
+    .option('--no-publish', 'Skip publishing local integration files before validate')
     .option(
       '--force',
       'With default sync, pass force to upload (same as aifabrix upload --force)'
@@ -61,7 +61,7 @@ function setupVerifyGovernanceCommand(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
     .option('-v, --verbose', 'Per-datasource breakdown and pipeline detail')
     .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/')
-    .option('--no-sync', 'Skip publishing local integration files before dataplane steps')
+    .option('--no-publish', 'Skip publishing local integration files before dataplane steps')
     .option(
       '--force',
       'With default sync, pass force to upload (same as aifabrix upload --force)'
@@ -108,7 +108,7 @@ function setupLifecycleCommand(program) {
     .option('-v, --verbose', 'Per-datasource breakdown in the report')
     .option('-d, --debug', 'Write debug logs under integration/<systemKey>/logs/ when --run')
     .option('--run', 'Run missing verify steps, then print certification report')
-    .option('--no-sync', 'With --run, skip publishing local integration files before verify')
+    .option('--no-publish', 'With --run, skip publishing local integration files before verify')
     .option(
       '--force',
       'With default sync on --run, pass force to upload (same as aifabrix upload --force)'

package/lib/cli/setup-certification.help.js

@@ -8,7 +8,7 @@ const VERIFY_OPERATIONS_HELP_AFTER = `
 Examples:
   $ aifabrix verify-operations hubspot
   $ aifabrix verify-operations hubspot -v
-  $ aifabrix verify-operations hubspot --no-sync
+  $ aifabrix verify-operations hubspot --no-publish
 
 Notes:
   - Orchestrates validate → test → test-integration → test-e2e for the system.
@@ -23,12 +23,12 @@ const VERIFY_TRUST_HELP_AFTER = `
 Examples:
   $ aifabrix verify-trust hubspot
   $ aifabrix verify-trust hubspot -v --revalidate
-  $ aifabrix verify-trust hubspot --no-sync --json
+  $ aifabrix verify-trust hubspot --no-publish --json
 
 Notes:
   - For one datasource: aifabrix datasource verify-trust <datasourceKey>
   - Does not call external vendor APIs (use verify-operations / test-e2e for connectivity).
-  - Local integration files are published before run unless --no-sync.
+  - Local integration files are published before run unless --no-publish.
 `;
 
 const VERIFY_GOVERNANCE_HELP_AFTER = `
@@ -38,7 +38,7 @@ Examples:
   $ aifabrix verify-governance hubspot-e2e --certification-profile gold --json
 
 Notes:
-  - All-in-one: publishes local integration (unless --no-sync), generates packs on the dataplane,
+  - All-in-one: publishes local integration (unless --no-publish), generates packs on the dataplane,
     then runs governance verification (dataplane-first; no local YAML upload).
   - Requires at least one --subject-user-id or --subject-email (repeatable or comma-separated).
   - Prefer this over separate generate + verify when certifying an integration.
@@ -50,12 +50,12 @@ const GOVERNANCE_GENERATE_HELP_AFTER = `
 Examples:
   $ aifabrix governance generate hubspot-e2e --subject-email us.sales@example.com
   $ aifabrix governance generate hubspot-e2e --subject-user-id user-a --subject-user-id user-b -v
-  $ aifabrix governance generate hubspot-e2e --certification-profile gold --no-sync
+  $ aifabrix governance generate hubspot-e2e --certification-profile gold --no-publish
 
 Notes:
   - Dataplane generates keys, coverage, and generationState; the CLI never authors partitions locally.
   - Requires at least one --subject-user-id or --subject-email per datasource fan-out.
-  - Publishes local integration files before generate unless --no-sync.
+  - Publishes local integration files before generate unless --no-publish.
 `;
 
 const GOVERNANCE_VERIFY_HELP_AFTER = `
@@ -74,7 +74,7 @@ Notes:
 const GOVERNANCE_UPLOAD_HELP_AFTER = `
 Examples:
   $ aifabrix governance upload hubspot-e2e
-  $ aifabrix governance upload hubspot-e2e --no-sync
+  $ aifabrix governance upload hubspot-e2e --no-publish
 
 Notes:
   - Expert path: pushes integration/<systemKey>/scenarios/*.yaml to the dataplane.
@@ -98,13 +98,13 @@ Examples:
   $ aifabrix lifecycle hubspot
   $ aifabrix lifecycle hubspot -v
   $ aifabrix lifecycle hubspot --run
-  $ aifabrix lifecycle hubspot --run --no-sync
+  $ aifabrix lifecycle hubspot --run --no-publish
   $ aifabrix lifecycle hubspot-e2e --run --subject-email us.sales@example.com
   $ aifabrix lifecycle hubspot-e2e --run --subject-email a@x.com,b@y.com -v
 
 Notes:
   - Default: certification report only (GET persisted pillar results from dataplane).
-  - --run executes missing verify steps, then prints the report (publishes local files first unless --no-sync).
+  - --run executes missing verify steps, then prints the report (publishes local files first unless --no-publish).
   - With --run, --subject-email / --subject-user-id generate and verify governance packs (same as verify-governance).
   - Repeat the flag or use comma-separated values: --subject-email a@x.com,b@y.com
   - One-shot cert path: lifecycle <systemKey> --run --subject-email <email>

package/lib/cli/setup-dev.js

@@ -12,7 +12,8 @@ const config = require('../core/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 { runDevInit } = require('../commands/dev-init');
+const { runDevRefresh, ensureDevCertFreshIfDue } = require('../commands/dev-refresh');
 const { displayDevConfig } = require('../commands/dev-show-display');
 const {
   handleDevList,
@@ -49,11 +50,21 @@ Examples:
 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 `dev list --help` (sort examples). */
+const DEV_LIST_HELP_AFTER = `
+Examples:
+  $ aifabrix dev list
+  $ aifabrix dev list --sort id
+  $ aifabrix dev list --sort -until
+
+Sort fields: id, name, email, until. Prefix - for descending (default: name ascending).
+`;
+
 /** 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)
+  Onboarding     init (PIN onboarding), refresh (sync settings / renew cert); show auto-renews when due
   Remote admin   list, add, update, pin, delete, platform-install, platform-update, platform-install-cli  (need remote-server + client cert in ~/.aifabrix)
   Sync / stop    down  (Mutagen; optional --apps for containers)
 
@@ -84,8 +95,8 @@ Examples:
   $ 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.
+Prints a shareable block for the developer: Node.js + Builder CLI install (Windows / Linux & macOS),
+then copy-paste dev init commands (standard, hosts-file variant, and dev init --pin when config exists).
 `;
 
 /** Appended to `dev delete --help`. */
@@ -168,9 +179,10 @@ async function handleSetScopedResources(value) {
 function setupDevShowAndSetId(dev) {
   dev
     .command('show')
-    .description('Show dev ports and ~/.aifabrix config')
+    .description('Show dev ports and ~/.aifabrix config (auto-renews cert when due)')
     .action(async() => {
       try {
+        await ensureDevCertFreshIfDue();
         const devId = await config.getDeveloperId();
         await displayDevConfig(devId);
       } catch (error) {
@@ -286,9 +298,14 @@ function setupDevListAddCommands(dev) {
   dev
     .command('list')
     .description('List developers (remote Builder Server)')
-    .action(async() => {
+    .option(
+      '--sort <field>',
+      'Sort field/direction (id|name|email|until; prefix - for descending; default name)'
+    )
+    .addHelpText('after', DEV_LIST_HELP_AFTER)
+    .action(async(options) => {
       try {
-        await handleDevList();
+        await handleDevList(options);
       } catch (error) {
         handleCommandError(error, 'dev list');
         process.exit(1);
@@ -311,6 +328,8 @@ function setupDevListAddCommands(dev) {
     .option('--skip-cert', 'Skip certificate step in provision job')
     .option('--skip-platform', 'Skip platform install in provision job')
     .option('--skip-cli', 'Skip Builder CLI install in provision job')
+    .option('--wait', 'Poll until provision job completes', true)
+    .option('--no-wait', 'Return after provision job is queued')
     .addHelpText('after', DEV_ADD_HELP_AFTER)
     .action(async(options) => {
       try {
@@ -384,6 +403,9 @@ function setupDevUpdatePinDeleteCommands(dev) {
     .description('Remove developer from host and server (admin)')
     .option('--db-only', 'Remove from server database only (legacy behaviour)')
     .option('-y, --yes', 'Skip confirmation prompt')
+    .option('--wait', 'Poll until removal completes on the host', true)
+    .option('--no-wait', 'Return after removal job is queued')
+    .option('--json', 'JSON output (includes job result when --wait)')
     .addHelpText('after', DEV_DELETE_HELP_AFTER)
     .action(async(developerId, options) => {
       try {
@@ -393,8 +415,6 @@ function setupDevUpdatePinDeleteCommands(dev) {
         process.exit(1);
       }
     });
-
-  setupDevDownCommand(dev);
 }
 
 /**
@@ -452,6 +472,7 @@ function setupDevPlatformCommands(dev) {
 function setupDevUserCommands(dev) {
   setupDevListAddCommands(dev);
   setupDevUpdatePinDeleteCommands(dev);
+  setupDevDownCommand(dev);
   setupDevPlatformCommands(dev);
 }
 

package/lib/cli/setup-external-system-help.js

@@ -8,24 +8,22 @@ const UPLOAD_HELP_AFTER = `
 Examples:
   # Publish integration/<systemKey>/ to the dataplane (typical lab flow after validate + resolve)
   $ aifabrix upload hubspot-demo
-  $ aifabrix upload hubspot-demo --verbose
+  $ aifabrix upload hubspot-demo -v
   $ aifabrix upload hubspot-demo --probe
 
   # Build and validate payload only (no API calls)
   $ aifabrix upload hubspot-demo --dry-run
 
-  # Short summary after publish
-  $ aifabrix upload hubspot-demo --minimal
-
   # Protection manifests (integration/.protection/ at repo root)
   $ aifabrix upload .protection
-  $ aifabrix upload .protection --warnings-as-errors --no-sync
+  $ aifabrix upload .protection --warnings-as-errors
 
 Notes:
   - Requires login (aifabrix auth status).
   - Reads files under integration/<systemKey>/ (system JSON, datasources, credentials).
+  - Default output is a compact readiness summary; use -v for expanded detail and server-side validate warnings.
   - --probe runs dataplane runtime checks after publish (slower; common in Session 1).
-  - test-e2e and test-integration publish local files first by default; use --no-sync on those commands to skip.
+  - test-e2e and test-integration publish local files first by default; use --no-publish on those commands to skip.
   - After dimension/FK edits on active datasources, use --force (or test-e2e / test-integration / datasource test-* with --sync --force).
   - For one datasource only: aifabrix datasource upload <datasourceKey>
 `;

package/lib/cli/setup-external-system.js

@@ -15,8 +15,7 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
-const { cliOptsSkipCertSync } = require('../certification/cli-cert-sync-skip');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 const { TEST_INTEGRATION_HELP_AFTER } = require('./setup-app.help');
 const {
   UPLOAD_HELP_AFTER,
@@ -24,6 +23,39 @@ const {
   DELETE_HELP_AFTER
 } = require('./setup-external-system-help');
 
+async function handleUploadCommandAction(systemKey, options) {
+  const { isProtectionScope } = require('../protection/scope');
+  if (isProtectionScope(systemKey)) {
+    const { uploadProtectionBatchCommand } = require('../protection/upload-batch');
+    const logger = require('../utils/logger');
+    const code = await uploadProtectionBatchCommand(
+      {
+        env: options.env,
+        dryRun: options.dryRun === true,
+        sync: options.sync === true,
+        json: options.json === true,
+        verbose: options.verbose === true,
+        warningsAsErrors: options.warningsAsErrors === true
+      },
+      logger
+    );
+    if (code !== 0) {
+      process.exit(code);
+    }
+    return;
+  }
+  const upload = require('../commands/upload');
+  const probeTimeout =
+    options.probeTimeout === undefined || options.probeTimeout === null
+      ? 120000
+      : Number(options.probeTimeout);
+  await upload.uploadExternalSystem(systemKey, {
+    ...options,
+    probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000,
+    pathOptions: {}
+  });
+}
+
 function setupDownloadCommand(program) {
   program.command('download <systemKey>')
     .description('Pull external system from dataplane into integration/<key>/')
@@ -31,6 +63,11 @@ function setupDownloadCommand(program) {
     .option('--format <format>', 'Output format: json | yaml (default: yaml or config format)')
     .option('--dry-run', 'Show what would be downloaded without actually downloading')
     .option('--force', 'Overwrite existing README.md without prompting')
+    .option(
+      '--version <target>',
+      'Manifest version to download (running default; latest or explicit id when supported)',
+      'running'
+    )
     .action(async(systemKey, options) => {
       try {
         const config = require('../core/config');
@@ -52,53 +89,22 @@ function setupUploadCommand(program) {
     .description('Validate, publish to dataplane, and register with controller (draft application); or upload .protection batch')
     .addHelpText('after', UPLOAD_HELP_AFTER)
     .option('--dry-run', 'Validate and build payload only; no API calls')
-    .option('--no-sync', 'For .protection: skip datasource sync after upload')
+    .option(
+      '--sync',
+      'After publish, run full datasource data sync for every datasource on the system (default: bootstrap-if-empty only)'
+    )
     .option('--json', 'For .protection: JSON output')
     .option('--warnings-as-errors', 'For .protection: pass strict=true to dataplane validate')
-    .option('-v, --verbose', 'Run server-side pipeline validate and print warnings before publish')
+    .option('-v, --verbose', 'Expanded upload summary and server-side pipeline validate warnings before publish')
     .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
-    .option('--minimal', 'Print only a short readiness summary after upload')
     .option('--probe-timeout <ms>', 'Timeout for --probe (default: 120000)', '120000')
-    .option(
-      '--no-cert-sync',
-      'Skip updating the system file certification block from the dataplane active certificate after publish'
-    )
     .option(
       '--force',
       'Bypass schema guards on active datasources during publish (dangerous; shows a warning)'
     )
     .action(async(systemKey, options) => {
       try {
-        const { isProtectionScope } = require('../protection/scope');
-        if (isProtectionScope(systemKey)) {
-          const { uploadProtectionBatchCommand } = require('../protection/upload-batch');
-          const logger = require('../utils/logger');
-          const code = await uploadProtectionBatchCommand(
-            {
-              env: options.env,
-              dryRun: options.dryRun === true,
-              noSync: options.noSync === true,
-              json: options.json === true,
-              verbose: options.verbose === true,
-              warningsAsErrors: options.warningsAsErrors === true
-            },
-            logger
-          );
-          if (code !== 0) {
-            process.exit(code);
-          }
-          return;
-        }
-        const upload = require('../commands/upload');
-        const probeTimeout =
-          options.probeTimeout === undefined || options.probeTimeout === null
-            ? 120000
-            : Number(options.probeTimeout);
-        await upload.uploadExternalSystem(systemKey, {
-          ...options,
-          noCertSync: cliOptsSkipCertSync(options),
-          probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000
-        });
+        await handleUploadCommandAction(systemKey, options);
       } catch (error) {
         handleCommandError(error, 'upload');
         process.exit(1);
@@ -181,7 +187,7 @@ async function runExternalSystemTestIntegration(appName, options) {
     environment: options.env || options.environment,
     debug: options.debug,
     perDatasource: options.perDatasource,
-    noSync: cliOptsSkipSync(options)
+    noPublish: cliOptsSkipPublish(options)
   };
   const results = await test.testExternalSystemIntegration(appName, opts);
   test.displayIntegrationTestResults(results, options.verbose, { debug: options.debug, runType: 'integration' });
@@ -192,9 +198,6 @@ async function runExternalSystemTestIntegration(appName, options) {
     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-integration');
 }
 
 /**
@@ -238,10 +241,7 @@ function setupExternalSystemTestCommands(program) {
     .option('-e, --env <env>', 'Environment: dev, tst, or pro (builder: dev/tst for container)', 'dev')
     .option('-v, --verbose', 'Show detailed test output')
     .option('-d, --debug', 'Include debug output and write log to integration/<systemKey>/logs/')
-    .option(
-      '--no-sync',
-      'Skip publishing local integration files; use system config already on the dataplane'
-    )
+    .option('--no-publish', 'Skip publishing local integration files before tests')
     .option(
       '--sync',
       'Publish local system and datasource files before tests (default for external integration; same as upload)'
@@ -250,12 +250,18 @@ function setupExternalSystemTestCommands(program) {
       '--force',
       'With --sync, pass force to upload (bypass active-datasource schema replacement guards; same as aifabrix upload --force)'
     )
-    .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'
+      '--version <target>',
+      'Manifest version for test (latest, running, or explicit version id)',
+      'latest'
     )
+    .option(
+      '--sync-mode <mode>',
+      'Sync policy during test: auto (default), never, or force. Distinct from --sync (publish local files).',
+      'auto'
+    )
+    .option('--warnings-as-errors', 'Treat aggregate warn as failure (exit 1)')
+    .option('--require-cert', 'Require certification passed on every datasource (exit 2 if not)')
     .addHelpText('after', TEST_INTEGRATION_HELP_AFTER)
     .action(async(appName, options, cmd) => {
       try {
@@ -264,7 +270,7 @@ function setupExternalSystemTestCommands(program) {
         const opts = {
           ...options,
           env: envExplicit ? options.env : undefined,
-          noSync: cliOptsSkipSync(options, cmd)
+          noPublish: cliOptsSkipPublish(options, cmd)
         };
         await runTestIntegrationCommand(appName, opts);
       } catch (error) {

package/lib/cli/setup-infra-up-builder-api-action.js

@@ -0,0 +1,64 @@
+/**
+ * `aifabrix up-builder-api` action body.
+ *
+ * @fileoverview up-builder-api CLI action
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { handleCommandError } = require('../utils/cli-utils');
+const { handleUpBuilderApi } = require('../commands/up-builder-api');
+const { cleanBuilderAppDirs, BUILDER_API_APP_KEYS } = require('../commands/up-common');
+const { recordInfraInstallationCommand } = require('./installation-log-command');
+
+/**
+ * @param {Object} options
+ * @returns {Promise<string[]>}
+ */
+async function runUpBuilderApiWork(options) {
+  let cleanedAppKeys = [];
+  if (options.force) {
+    const cleaned = await cleanBuilderAppDirs([...BUILDER_API_APP_KEYS]);
+    cleanedAppKeys = Array.isArray(cleaned) ? cleaned : [];
+  }
+  await handleUpBuilderApi(options);
+  return cleanedAppKeys;
+}
+
+/**
+ * @param {Object} options
+ * @returns {Promise<void>}
+ */
+async function handleUpBuilderApiCliAction(options) {
+  const startedAt = new Date();
+  let cleanedAppKeys = [];
+  try {
+    cleanedAppKeys = await runUpBuilderApiWork(options);
+    await recordInfraInstallationCommand({
+      command: 'up-builder-api',
+      options,
+      startedAt,
+      outcome: 'success',
+      platformAppList: ['builder-api'],
+      cleanup: cleanedAppKeys.length > 0 ? { cleanedAppKeys } : undefined
+    });
+  } catch (error) {
+    await recordInfraInstallationCommand({
+      command: 'up-builder-api',
+      options,
+      startedAt,
+      outcome: 'failure',
+      error,
+      platformAppList: ['builder-api'],
+      cleanup: cleanedAppKeys.length > 0 ? { cleanedAppKeys } : undefined
+    });
+    handleCommandError(error, 'up-builder-api');
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  handleUpBuilderApiCliAction
+};

package/lib/cli/setup-infra-up-platform-action.js

@@ -16,6 +16,7 @@ const { resolveControllerUrl } = require('../utils/controller-url');
 const { handleLogin } = require('../commands/login');
 const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
+const { handleUpBuilderApi } = require('../commands/up-builder-api');
 const {
   applyUpPlatformForceConfig,
   cleanBuilderAppDirs,
@@ -25,7 +26,7 @@ const {
 const { runGuidedUpPlatform } = require('./infra-guided');
 const { recordInfraInstallationCommand } = require('./installation-log-command');
 
-const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane'];
+const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane', 'builder-api'];
 
 /**
  * @param {Object} options
@@ -57,6 +58,7 @@ async function runUpPlatformWork(options) {
     await prepareUrlsLocalRegistryForUpPlatform();
     await handleUpMiso(options);
     await handleUpDataplane(options);
+    await handleUpBuilderApi({ ...options, platformInstall: true });
   }
   return cleanedAppKeys;
 }

package/lib/cli/setup-infra.js

@@ -285,6 +285,20 @@ function setupUpDataplaneCommand(program) {
     });
 }
 
+function setupUpBuilderApiCommand(program) {
+  program.command('up-builder-api')
+    .description('Materialize and run builder-api locally (dev env; needs up-infra; dataplane recommended)')
+    .option('-r, --registry <url>', 'Override registry for builder-api image')
+    .option('--registry-mode <mode>', 'Override registry mode (acr|external)')
+    .option('-i, --image <ref>', 'Override builder-api image reference')
+    .option('-f, --force', 'Clean builder/builder-api and re-fetch from templates')
+    .option('--verbose', 'Show full orchestration output')
+    .action((options) => {
+      const { handleUpBuilderApiCliAction } = require('./setup-infra-up-builder-api-action');
+      return handleUpBuilderApiCliAction(options);
+    });
+}
+
 function setupDownInfraCommand(program) {
   program.command('down-infra [service|app]')
     .description('Stop all infra, or stop one app; use -v to remove volumes')
@@ -418,6 +432,7 @@ function setupInfraCommands(program) {
   setupUpPlatformCommand(program);
   setupUpMisoCommand(program);
   setupUpDataplaneCommand(program);
+  setupUpBuilderApiCommand(program);
   setupDownInfraCommand(program);
   setupDoctorCommand(program);
   setupStatusCommand(program);

package/lib/cli/setup-list.js

@@ -0,0 +1,43 @@
+/**
+ * Top-level connected-system list command.
+ *
+ * @fileoverview aifabrix list — dataplane external systems
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { listExternalSystemsOnDataplane } = require('../app/list-external-systems');
+
+const LIST_HELP_AFTER = `
+Lists connected systems published on the dataplane (not controller pipeline applications).
+
+Examples:
+  aifabrix list
+  aifabrix list --json
+
+Controller applications only: aifabrix app list
+Show one system: aifabrix show <systemKey> --online
+`;
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupListCommand(program) {
+  program
+    .command('list')
+    .description('List connected systems on the dataplane')
+    .option('--json', 'Output as JSON')
+    .addHelpText('after', LIST_HELP_AFTER)
+    .action(async(options) => {
+      try {
+        await listExternalSystemsOnDataplane({ json: options.json === true });
+      } catch (error) {
+        logger.error(chalk.red(`Error: ${error.message}`));
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { setupListCommand };

package/lib/cli/setup-utility-help-after.js

@@ -18,6 +18,17 @@ Examples:
   $ aifabrix validate --builder
 `;
 
+const VALIDATE_JSON_HELP_AFTER = `
+Examples:
+  $ aifabrix validate-json myapp
+  $ aifabrix validate-json my-system
+  $ aifabrix validate-json --integration
+  $ aifabrix validate-json --builder
+  $ aifabrix validate-json --integration --builder --format json
+
+Runs full local validation first; writes *-deploy.json only when validation succeeds (offline).
+`;
+
 const REPAIR_HELP_AFTER = `
 Examples:
   $ aifabrix repair hubspot-demo
@@ -63,6 +74,7 @@ Examples:
 module.exports = {
   JSON_HELP_AFTER,
   VALIDATE_HELP_AFTER,
+  VALIDATE_JSON_HELP_AFTER,
   REPAIR_HELP_AFTER,
   RESOLVE_HELP_AFTER
 };