@aifabrix/builder 2.45.0 → 2.45.5

package/lib/cli/setup-app.js

@@ -16,14 +16,23 @@ const { setupInstallTestE2eLintCommands } = require('./setup-app.test-commands')
 
 const CREATE_HELP_AFTER = `
 Examples:
+  # Builder app → builder/<appKey>/
   $ aifabrix create myapi --type webapp -l typescript
-  $ aifabrix create mycrm --wizard
+  $ aifabrix create mysvc --type api -l python
+
+  # External system → integration/<systemKey>/ (default --type external)
+  $ aifabrix create hubspot --wizard
+  $ aifabrix create mycrm --type external --display-name "My CRM" --description "..." \\
+      --system-type openapi --auth-type oauth2 --entity-type recordStorage --datasources 1
+
+Positional: appKey for builder types; systemKey for --type external (folder under integration/).
+Prefer aifabrix wizard [systemKey] for guided external setup.
 `;
 
 const DEPLOY_HELP_AFTER = `
 Examples:
-  $ aifabrix deploy myapp
-  $ aifabrix deploy myext --local
+  $ aifabrix deploy myapp              # builder appKey → builder/myapp/
+  $ aifabrix deploy hubspot --local    # systemKey → integration/hubspot/
 `;
 
 const PUSH_HELP_AFTER = `
@@ -133,8 +142,8 @@ async function handleCreateCommand(appName, options) {
 }
 
 function setupCreateCommand(program) {
-  program.command('create <app>')
-    .description('Scaffold builder or external app (flags or --wizard)')
+  program.command('create <appKey|systemKey>')
+    .description('Create builder app (builder/<appKey>/) or external system (integration/<systemKey>/; --type, flags, or --wizard)')
     .addHelpText('after', CREATE_HELP_AFTER)
     .option('-p, --port <port>', 'Application port', '3000')
     .option('-d, --database', 'Requires database')
@@ -148,7 +157,7 @@ function setupCreateCommand(program) {
     .option('-g, --github', 'Generate GitHub Actions workflows')
     .option('--github-steps <steps>', 'Extra GitHub workflow steps (comma-separated, e.g., npm,test)')
     .option('--main-branch <branch>', 'Main branch name for workflows', 'main')
-    .option('--wizard', 'Use interactive wizard for external system creation')
+    .option('--wizard', 'Run wizard for external system (systemKey → integration/<systemKey>/; same as aifabrix wizard)')
     .option('--display-name <name>', 'External system display name')
     .option('--description <desc>', 'External system description')
     .option('--system-type <type>', 'External system type (openapi, mcp, custom)')
@@ -209,8 +218,8 @@ Examples:
   $ aifabrix run myapp --base
   $ aifabrix run myapp --reload
   $ aifabrix run myapp --no-proxy   # same as --proxy false: localhost for Docker declarative public URLs; saves applications.<app>.proxy: false`;
-  program.command('run <app>')
-    .description('Run app locally or on remote Docker host')
+  program.command('run <appKey>')
+    .description('Run builder app by appKey locally or on remote Docker host')
     .option('-p, --port <port>', 'Override local port')
     .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')
@@ -238,8 +247,8 @@ Examples:
 }
 
 function setupBuildRunLogsDownCommands(program) {
-  program.command('build <app>')
-    .description('Build Docker image (auto-detect runtime)')
+  program.command('build <appKey>')
+    .description('Build Docker image for builder appKey (auto-detect runtime)')
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force-template', 'Force rebuild from template')
     .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
@@ -257,8 +266,8 @@ function setupBuildRunLogsDownCommands(program) {
 
   registerRunCommand(program);
 
-  program.command('logs <app>')
-    .description('Tail app container logs (optional env summary; secrets masked)')
+  program.command('logs <appKey>')
+    .description('Tail container logs for appKey (optional env summary; secrets masked)')
     .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)')
@@ -275,8 +284,8 @@ function setupBuildRunLogsDownCommands(program) {
       }
     });
 
-  program.command('down-app <app>')
-    .description('Stop and remove app container (--volumes removes data volume)')
+  program.command('down-app <appKey>')
+    .description('Stop and remove container for appKey (--volumes removes data volume)')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -290,8 +299,8 @@ function setupBuildRunLogsDownCommands(program) {
 }
 
 function setupShellTestStopCommands(program) {
-  program.command('stop <app>')
-    .description('Alias for down-app: stop and remove container')
+  program.command('stop <appKey>')
+    .description('Alias for down-app: stop and remove container for appKey')
     .option('--volumes', 'Remove application Docker volume')
     .action(async(appName, options) => {
       try {
@@ -303,8 +312,8 @@ function setupShellTestStopCommands(program) {
       }
     });
 
-  program.command('shell <app>')
-    .description('Interactive shell in running or ephemeral container')
+  program.command('shell <appKey>')
+    .description('Interactive shell in container for builder appKey')
     .option('--env <env>', 'Environment (dev|tst); dev uses running container', 'dev')
     .action(async(appName, options) => {
       try {
@@ -318,8 +327,8 @@ function setupShellTestStopCommands(program) {
 }
 
 function setupDockerfileGenerateCommand(program) {
-  program.command('dockerfile <app>')
-    .description('Generate Dockerfile from detected runtime')
+  program.command('dockerfile <appKey>')
+    .description('Generate Dockerfile for builder appKey from detected runtime')
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force', 'Overwrite existing Dockerfile')
     .action(async(appName, options) => {
@@ -335,8 +344,8 @@ function setupDockerfileGenerateCommand(program) {
 }
 
 function setupPushDeployDockerfileCommands(program) {
-  program.command('push <app>')
-    .description('Push image to Azure Container Registry')
+  program.command('push <appKey>')
+    .description('Push builder appKey image to Azure Container Registry')
     .addHelpText('after', PUSH_HELP_AFTER)
     .option('-r, --registry <registry>', 'ACR registry URL (overrides application.yaml)')
     .option('-t, --tag <tag>', 'Image tag(s) - comma-separated for multiple (default: latest)')
@@ -349,8 +358,8 @@ function setupPushDeployDockerfileCommands(program) {
       }
     });
 
-  program.command('deploy <app>')
-    .description('Deploy via Miso Controller (Azure or --local)')
+  program.command('deploy <appKey|systemKey>')
+    .description('Deploy builder app or external system via Miso Controller (Azure or --local)')
     .addHelpText('after', DEPLOY_HELP_AFTER)
     .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)')

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

@@ -8,11 +8,16 @@ 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');
+const {
+  TEST_HELP_AFTER,
+  TEST_E2E_HELP_AFTER,
+  TEST_TRUST_HELP_AFTER,
+  TEST_GOVERNANCE_HELP_AFTER
+} = require('./setup-app.help');
 
 function setupTestCommand(program) {
-  program.command('test <app>')
-    .description('Tests: builder in container; external = local validation')
+  program.command('test <appKey|systemKey>')
+    .description('Tests: builder appKey in container; external systemKey = 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)')
@@ -84,14 +89,16 @@ function firstIssuanceFailureHintFromE2eResults(results) {
  * @param {Object} options
  * @returns {Promise<void>}
  */
-async function runExternalIntegrationE2EAndCertSync(appName, options) {
+async function runExternalIntegrationE2EAndCertSync(appName, options, cmd) {
+  const { cliOptsSkipSync } = require('../utils/cli-sync-options');
   const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+  const noSync = cliOptsSkipSync(options, cmd);
   const { success, results } = await runTestE2EForExternalSystem(appName, {
     env: options.env,
     debug: options.debug,
     verbose: options.verbose,
     async: options.async !== false,
-    noSync: options.noSync === true
+    noSync
   });
   const { displayIntegrationTestResults } = require('../utils/external-system-display');
   const datasourceResults = results.map(r => ({
@@ -118,17 +125,19 @@ async function runExternalIntegrationE2EAndCertSync(appName, options) {
   await trySyncCertificationFromDataplaneForExternalApp(appName, 'test-e2e', { issuanceFailureHint });
 }
 
-async function runTestE2ECommand(appName, options) {
+async function runTestE2ECommand(appName, options, cmd) {
+  const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+  const noSync = cliOptsSkipSync(options, cmd);
   const pathsUtil = require('../utils/paths');
   const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-  if (options.noSync === true && appType && appType.baseDir === 'builder') {
+  if (noSync && appType && appType.baseDir === 'builder') {
     throw new Error(
       'Option --no-sync applies only to external integration E2E (integration/<systemKey>/). ' +
         'Remove --no-sync for builder app E2E.'
     );
   }
   if (appType && appType.baseDir === 'integration') {
-    await runExternalIntegrationE2EAndCertSync(appName, options);
+    await runExternalIntegrationE2EAndCertSync(appName, options, cmd);
     return;
   }
   const { runAppTestE2e } = require('../commands/app-test');
@@ -136,8 +145,8 @@ async function runTestE2ECommand(appName, options) {
 }
 
 function setupInstallCommand(program) {
-  program.command('install <app>')
-    .description('Install deps in container (builder apps only)')
+  program.command('install <appKey>')
+    .description('Install deps in container (builder appKey only)')
     .option('--env <env>', 'dev (running container) or tst (ephemeral with .env)', 'dev')
     .action(async(appName, options) => {
       try {
@@ -145,7 +154,7 @@ function setupInstallCommand(program) {
         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.')
+            chalk.gray('Install is for builder appKey only. Use aifabrix shell <appKey> for builder apps or External Systems commands for integrations.')
           );
           return;
         }
@@ -159,15 +168,11 @@ function setupInstallCommand(program) {
 }
 
 function setupTestE2eCommand(program) {
-  program.command('test-e2e <app>')
-    .description('E2E: builder in container; external = all datasources via dataplane')
+  program.command('test-e2e <appKey|systemKey>')
+    .description('E2E: builder appKey in container; external systemKey = 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',
-      '(Deprecated; no-op.) Local integration files are published before E2E by default; use --no-sync to skip.'
-    )
     .option(
       '--no-sync',
       'Skip publishing local integration files; E2E uses the system config already on the dataplane (external integration only)'
@@ -188,7 +193,7 @@ function setupTestE2eCommand(program) {
           env: envExplicit ? options.env : undefined,
           async: true // system-level command surface omits --no-async; always poll for completeness
         };
-        await runTestE2ECommand(appName, externalOpts);
+        await runTestE2ECommand(appName, externalOpts, cmd);
       } catch (error) {
         handleCommandError(error, 'test-e2e');
         process.exit(1);
@@ -197,15 +202,15 @@ function setupTestE2eCommand(program) {
 }
 
 function setupLintCommand(program) {
-  program.command('lint <app>')
-    .description('Lint in container (builder apps only)')
+  program.command('lint <appKey>')
+    .description('Lint in container (builder appKey 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.'));
+          logger.log(chalk.gray('lint is for builder appKey only. Use aifabrix shell <appKey> then make lint or pnpm lint.'));
           return;
         }
         const { runAppLint } = require('../commands/app-test');
@@ -217,10 +222,64 @@ function setupLintCommand(program) {
     });
 }
 
+function collectScenarioId(value, previous) {
+  return previous.concat([value]);
+}
+
+function setupTestGovernanceCommand(program) {
+  const { testGovernanceCommandHandler } = require('../commands/test-governance-command-action');
+  program
+    .command('test-governance <appKey|systemKey>')
+    .description(
+      'Governance scenario acceptance: ABAC visibility via governed search (key sets only)'
+    )
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('--pack <path>', 'Scenario pack YAML (default: scenarios/default.yaml or <systemKey>-v1.yaml)')
+    .option('-a, --app <path>', 'Integration folder override')
+    .option(
+      '--scenario <id>',
+      'Run subset of scenario ids (repeatable)',
+      collectScenarioId,
+      []
+    )
+    .option('--no-sync', 'Skip publishing local integration files before run')
+    .option('-v, --verbose', 'Per-scenario verdict lines with subject and counts')
+    .option('--json', 'Machine-readable redacted result (same allowlist as API)')
+    .addHelpText('after', TEST_GOVERNANCE_HELP_AFTER)
+    .action((appName, options, cmd) => testGovernanceCommandHandler(appName, options, cmd));
+}
+
+function setupTestTrustCommand(program) {
+  const { testTrustCommandHandler } = require('../commands/test-trust-command-action');
+  program
+    .command('test-trust <appKey|systemKey>')
+    .description(
+      'Semantic agent metadata validation for external system (all datasources via dataplane 404.5)'
+    )
+    .option('-e, --env <env>', 'Environment: dev, tst, or pro', 'dev')
+    .option('-v, --verbose', 'Show findings and observed business model')
+    .option('-d, --debug', 'Write debug log under integration/<systemKey>/logs/')
+    .option('--no-sync', 'Skip publishing local integration files before validate')
+    .option('--revalidate', 'Force new validation for each datasource')
+    .option(
+      '--timeout <ms>',
+      'HTTP timeout for validate/latest requests (ms)',
+      '120000'
+    )
+    .option('--strict', 'Exit 1 unless every datasource is trusted')
+    .option('--warnings-as-errors', 'Exit 1 when any datasource is usableWithWarnings')
+    .option('--json', 'Print JSON array of trust runs')
+    .option('--summary', 'One line per datasource')
+    .addHelpText('after', TEST_TRUST_HELP_AFTER)
+    .action((appName, options, cmd) => testTrustCommandHandler(appName, options, cmd));
+}
+
 function setupInstallTestE2eLintCommands(program) {
   setupInstallCommand(program);
   setupTestCommand(program);
   setupTestE2eCommand(program);
+  setupTestGovernanceCommand(program);
+  setupTestTrustCommand(program);
   setupLintCommand(program);
 }
 

package/lib/cli/setup-auth.js

@@ -28,7 +28,33 @@ For details on omitting the URL: aifabrix auth set-controller -h
 Aliases:
   aifabrix auth set-controller [url]
   aifabrix auth set-environment <env>
-Subcommand: auth status [--validate] for CI/scripts.
+Subcommand: auth status [--validate] for CI/scripts (exit codes 0/1/3).
+`;
+
+const AUTH_STATUS_HELP_AFTER = `
+Examples:
+  $ aifabrix auth status
+  $ aifabrix auth status --validate
+
+Exit codes (--validate only):
+  0  Authenticated and Builder CLI meets dataplane minimum (or no minimum configured)
+  1  Not authenticated — run aifabrix login
+  3  Authenticated but Builder CLI is older than dataplane minimum
+
+Config cache (written on status when dataplane is reachable):
+  ~/.aifabrix/config.yaml → device.<controllerUrl>:
+    dataplane-version         — last dataplane version from health
+    dataplane-min-cli-version — minimum Builder CLI required (when enforced)
+
+What is blocked when CLI is too old:
+  Dataplane commands (upload, wizard, datasource upload, deploy to dataplane, …)
+What still works:
+  Local validate, aifabrix run, up-infra, file generation without dataplane API calls
+
+Troubleshooting:
+  • "Upgrade required" but you upgraded — run auth status again to refresh cache
+  • No min version shown — dataplane MIN_BUILDER_CLI_VERSION not set (ops)
+  • CI exit 3 — pin @aifabrix/builder version in pipeline to ≥ dataplane-min-cli-version
 `;
 
 const AUTH_SET_CONTROLLER_HELP_AFTER = `
@@ -168,7 +194,8 @@ function setupAuthSubcommands(program) {
 
   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)')
+    .addHelpText('after', AUTH_STATUS_HELP_AFTER)
+    .option('--validate', 'Exit 1 when not authenticated, 3 when Builder CLI < dataplane minimum, 0 otherwise (for CI/scripts)')
     .action(createAuthStatusAction());
 }
 
@@ -182,4 +209,4 @@ function setupAuthCommands(program) {
   setupAuthSubcommands(program);
 }
 
-module.exports = { setupAuthCommands };
+module.exports = { setupAuthCommands, AUTH_STATUS_HELP_AFTER };

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

@@ -42,8 +42,11 @@ function setupDownloadCommand(program) {
 
 function setupUploadCommand(program) {
   program.command('upload <systemKey>')
-    .description('Validate, publish to dataplane, and register with controller (draft application)')
+    .description('Validate, publish to dataplane, and register with controller (draft application); or upload .protection batch')
     .option('--dry-run', 'Validate and build payload only; no API calls')
+    .option('--no-sync', 'For .protection: skip datasource sync after upload')
+    .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('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
     .option('--minimal', 'Print only a short readiness summary after upload')
@@ -54,6 +57,26 @@ function setupUploadCommand(program) {
     )
     .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
@@ -79,6 +102,17 @@ function setupDeleteCommand(program) {
     .option('--force', 'Skip confirmation prompt (alias for --yes)')
     .action(async(systemKey, options) => {
       try {
+        const { isProtectionScope } = require('../protection/scope');
+        if (isProtectionScope(systemKey)) {
+          const logger = require('../utils/logger');
+          const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+          logger.error(
+            formatBlockingError(
+              'delete .protection is not supported. Use: aifabrix protection delete <datasourceKey>'
+            )
+          );
+          process.exit(1);
+        }
         const externalDelete = require('../external-system/delete');
         await externalDelete.deleteExternalSystem(systemKey, options);
       } catch (error) {
@@ -186,8 +220,8 @@ async function runTestIntegrationCommand(appName, options) {
 
 function setupExternalSystemTestCommands(program) {
   // 'test <app>' is registered in setup-app.js and dispatches by app type (builder vs external)
-  program.command('test-integration <app>')
-    .description('Integration tests: builder in container; external via dataplane')
+  program.command('test-integration <appKey|systemKey>')
+    .description('Integration tests: builder appKey in container; external systemKey via dataplane')
     .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/')

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

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Help-after strings for setup-utility CLI commands.
+ */
+
+'use strict';
+
+const JSON_HELP_AFTER = `
+Example:
+  $ aifabrix json myapp
+Generates *-deploy.json (or application-schema.json) for commit before deploy.
+`;
+
+const VALIDATE_HELP_AFTER = `
+Examples:
+  $ aifabrix validate myapp
+  $ aifabrix validate myapp --cert-sync
+  $ aifabrix validate --integration
+  $ aifabrix validate --builder
+`;
+
+const REPAIR_HELP_AFTER = `
+Examples:
+  $ aifabrix repair hubspot-demo
+    Align manifest, system/datasource files, RBAC extract, env.template, and deploy JSON under integration/<systemKey>/.
+
+  $ aifabrix repair hubspot-demo --dry-run
+    Show what would change without writing files.
+
+  $ aifabrix repair hubspot-demo --auth oauth2
+    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, basic, …).
+
+  $ aifabrix repair hubspot-demo --rbac --expose --sync --test
+    Optional datasource fixes: RBAC roles/permissions, exposed.schema from attributes, default sync block, testPayload stubs.
+
+  $ aifabrix repair hubspot-demo --doc
+    Regenerate README.md from the current deployment manifest only (other drift fixes unchanged).
+
+  Before overwriting files, repair writes timestamped backups under integration/<systemKey>/backup/ (same as datasource capability copy). Use --no-backup to skip.
+`;
+
+module.exports = {
+  JSON_HELP_AFTER,
+  VALIDATE_HELP_AFTER,
+  REPAIR_HELP_AFTER
+};

package/lib/cli/setup-utility-resolve.js

@@ -114,8 +114,8 @@ async function runResolveAppAction(appName, options) {
  * @returns {void}
  */
 function setupResolveCommand(program) {
-  program.command('resolve <app>')
-    .description('Generate .env from template; optional validate after')
+  program.command('resolve <appKey|systemKey>')
+    .description('Generate .env from template (builder/<appKey>/ or integration/<systemKey>/); optional validate after')
     .option('-f, --force', 'Generate missing secret keys in secrets file')
     .option('--skip-validation', 'Skip file validation after generating .env')
     .option('--json', 'Print JSON summary (envPath, manifestSource, optional validation)')