@aifabrix/builder 2.44.5 → 2.45.0

package/lib/cli/setup-platform.js

@@ -0,0 +1,102 @@
+/**
+ * CLI registration for `aifabrix setup` and `aifabrix teardown`.
+ *
+ * `setup` is the one-shot platform installer. When no infrastructure is
+ * detected it runs a small wizard (admin email/password, AI tool keys) and
+ * then `up-infra` + `up-platform`. When infra is already up, it offers a
+ * mode menu (re-install, wipe data, clean install files, update images).
+ *
+ * `teardown` is the symmetrical inverse of `setup`: `down-infra -v` plus a
+ * full clean of the AI Fabrix system directory (everything except
+ * `config.yaml`).
+ *
+ * @fileoverview CLI command setup for setup/teardown
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const { handleCommandError } = require('../utils/cli-utils');
+const { handleSetup } = require('../commands/setup');
+const { handleTeardown } = require('../commands/teardown');
+
+const SETUP_HELP_AFTER = `
+What this command does:
+  - With no infra running: prompts for admin email/password (used for Postgres, pgAdmin, Keycloak). The email is saved as adminEmail in config.yaml so the next setup can show it as the default (you can still change it). Prompts for an AI tool (OpenAI or Azure OpenAI) only when keys are not already set, then runs up-infra and up-platform.
+  - With infra running: shows a mode menu:
+      1) Re-install — stop infra and remove all volumes, then up-infra + up-platform --force.
+      2) Wipe data — drop every database and DB user, then up-infra + up-platform --force.
+      3) Clean installation files — remove user-local secrets, then up-infra + up-platform --force.
+      4) Update images — pull the latest infra and platform images, then up-infra + up-platform.
+
+AI tool keys are read from the user-local file (~/.aifabrix/secrets.local.yaml) merged with the shared aifabrix-secrets file. If either source already provides keys, the AI tool prompt is skipped.
+
+Use 'aifabrix teardown' to fully remove the local installation.
+`;
+
+const TEARDOWN_HELP_AFTER = `
+What this command does:
+  - Runs down-infra -v (stops all infra + apps, removes every Docker volume).
+  - Removes every file and subfolder inside ~/.aifabrix/ EXCEPT config.yaml.
+    This includes secrets.local.yaml, admin-secrets.env, auth/token files,
+    and infra-dev*/ directories.
+
+This is the symmetrical inverse of 'aifabrix setup'. Use --yes / -y to skip the confirmation prompt in CI.
+`;
+
+/**
+ * Register the setup command on the Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerSetup(program) {
+  program
+    .command('setup')
+    .description('Install or refresh the full AI Fabrix platform (infra + miso + dataplane)')
+    .option('-d, --developer <id>', 'Pin developer ID before fresh install (fresh path only; ignored when infra is already up)')
+    .option('-y, --yes', 'Skip destructive confirmation prompts (re-install, wipe data, teardown)')
+    .addHelpText('after', SETUP_HELP_AFTER)
+    .action(async(options) => {
+      try {
+        await handleSetup(options || {});
+      } catch (error) {
+        handleCommandError(error, 'setup');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Register the teardown command on the Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerTeardown(program) {
+  program
+    .command('teardown')
+    .description('Tear down local AI Fabrix infra and clean ~/.aifabrix/ except config.yaml')
+    .option('-y, --yes', 'Skip the confirmation prompt')
+    .addHelpText('after', TEARDOWN_HELP_AFTER)
+    .action(async(options) => {
+      try {
+        await handleTeardown(options || {});
+      } catch (error) {
+        handleCommandError(error, 'teardown');
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Register all setup-platform commands on the Commander program.
+ * @param {import('commander').Command} program
+ */
+function setupPlatformCommands(program) {
+  registerSetup(program);
+  registerTeardown(program);
+}
+
+module.exports = {
+  setupPlatformCommands,
+  registerSetup,
+  registerTeardown
+};

package/lib/cli/setup-secrets.js

@@ -24,8 +24,8 @@ Subcommands:
 
 Also: aifabrix secure   Encrypt secrets.local.yaml (ISO 27001)
 
-Default "secret set" (no --shared): writes only to your user secrets.local.yaml next to
-  config.yaml (typically ~/.aifabrix/secrets.local.yaml). Use --shared to write the
+Default "secret set" (no --shared): writes only to your user secrets.local.yaml under the
+  resolved AI Fabrix home (config key aifabrix-home, else ~/.aifabrix). Use --shared to write the
   shared store from config aifabrix-secrets (another file or https), not that user file.
 
 Examples:
@@ -46,8 +46,8 @@ Examples:
 
 const SECRET_SET_HELP_AFTER = `
 Where the value is stored:
-  No --shared   User file secrets.local.yaml in your aifabrix config directory (same
-                folder as config.yaml; often ~/.aifabrix/). Used for app/integration
+  No --shared   User file secrets.local.yaml under the resolved AI Fabrix home
+                (config key aifabrix-home, else ~/.aifabrix/). Used for app/integration
                 secrets and kv:// resolution on your machine.
   --shared      The store set in config.yaml as aifabrix-secrets: a YAML file path or
                 an https secrets API (never the user-only file above unless you point
@@ -70,6 +70,13 @@ Examples:
 `;
 
 const SECRET_REMOVE_ALL_HELP_AFTER = `
+Where keys are removed:
+  Default       All keys in your user secrets.local.yaml (under resolved aifabrix home,
+                often ~/.aifabrix/). This is NOT the shared store unless you deliberately
+                point aifabrix-secrets there.
+  --shared      Every key in the shared store from config aifabrix-secrets (YAML file
+                path or https secrets API). Requires that setting; use secret set-secrets-file if needed.
+
 You will be asked to type "yes" to confirm unless you pass --yes.
 
 Examples:
@@ -103,9 +110,14 @@ function setupSecretRemoveAllCommand(secretCmd) {
   const { handleSecretsRemoveAll } = require('../commands/secrets-remove-all');
   secretCmd
     .command('remove-all')
-    .description('Remove all secret keys (requires typing "yes" unless --yes)')
+    .description(
+      'Remove every key from user secrets.local.yaml (add --shared for aifabrix-secrets store; confirm unless --yes)'
+    )
     .addHelpText('after', SECRET_REMOVE_ALL_HELP_AFTER)
-    .option('--shared', 'Remove all from shared secrets (file or remote API)')
+    .option(
+      '--shared',
+      'Remove every key from shared secrets (config aifabrix-secrets: YAML file or https API)'
+    )
     .option('-y, --yes', 'Skip confirmation prompt (non-interactive / scripts)')
     .action(async options => {
       try {

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

@@ -0,0 +1,132 @@
+/**
+ * `aifabrix resolve <app>` command wiring (split from setup-utility for file/function size limits).
+ *
+ * @fileoverview Resolve CLI command
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const secrets = require('../core/secrets');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const coreConfig = require('../core/config');
+const { resolvePreferLocalEnvOutputPathFlag } = require('../utils/applications-config-defaults');
+const { getResolveAppPath } = require('../utils/paths');
+
+/**
+ * @param {string} appName
+ * @param {string} appPath
+ * @param {boolean} envOnly
+ * @param {string} envPath
+ * @param {{ skipValidation?: boolean }} options
+ * @param {{ getManifestSourcePayload: function }} manifestEmit
+ * @returns {Promise<void>}
+ */
+async function runResolveJsonOutput(appName, appPath, envOnly, envPath, options, manifestEmit) {
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    app: appName,
+    appPath,
+    envOnly,
+    envPath,
+    manifestSource: envOnly ? null : manifestEmit.getManifestSourcePayload(appName, appPath)
+  };
+  if (!envOnly && !options.skipValidation) {
+    const validate = require('../validation/validate');
+    payload.validation = await validate.validateAppOrFile(appName);
+  }
+  logger.log(JSON.stringify(payload, null, 2));
+  const v = payload.validation;
+  if (v && typeof v === 'object' && v.valid === false) {
+    process.exit(1);
+  }
+}
+
+/**
+ * @param {string} appName
+ * @param {string} envPath
+ * @param {boolean} envOnly
+ * @param {{ skipValidation?: boolean }} options
+ * @returns {Promise<void>}
+ */
+async function runResolveHumanOutput(appName, envPath, envOnly, options) {
+  logger.log(`✔ Generated .env file: ${envPath}`);
+  logger.log(chalk.gray('  Note: up-platform / up-miso / up-dataplane / register / build resolve secrets in memory only.'));
+  logger.log(chalk.gray(`  Re-run "aifabrix resolve ${appName}" whenever you need an on-disk .env again.`));
+  if (envOnly) {
+    logger.log(chalk.gray('  (env-only mode: validation skipped; no application config file)'));
+    return;
+  }
+  if (options.skipValidation) {
+    return;
+  }
+  const validate = require('../validation/validate');
+  const result = await validate.validateAppOrFile(appName);
+  validate.displayValidationResults(result);
+  if (!result.valid) {
+    logger.log(chalk.yellow('\n⚠  Validation found errors. Fix them before deploying.'));
+    process.exit(1);
+  }
+}
+
+/**
+ * @param {string} appName
+ * @param {{ force?: boolean, skipValidation?: boolean, json?: boolean }} options
+ * @returns {Promise<void>}
+ */
+async function runResolveAppAction(appName, options) {
+  const jsonMode = options.json === true;
+  const { appPath, envOnly } = await getResolveAppPath(appName);
+  const manifestEmit = require('../utils/manifest-source-emit');
+  manifestEmit.emitManifestMetadataLineIfTTY(logger, {
+    appKey: appName,
+    appPath,
+    envOnly,
+    json: jsonMode
+  });
+  const userCfg = await coreConfig.getConfig();
+  const preferLocalEnvOutputPath = await resolvePreferLocalEnvOutputPathFlag(userCfg, appName);
+  const envPath = await secrets.generateEnvFile(
+    appName,
+    undefined,
+    'docker',
+    options.force,
+    {
+      appPath,
+      envOnly,
+      skipOutputPath: false,
+      preserveFromPath: null,
+      preferLocalEnvOutputPath
+    }
+  );
+  if (jsonMode) {
+    await runResolveJsonOutput(appName, appPath, envOnly, envPath, options, manifestEmit);
+    return;
+  }
+  await runResolveHumanOutput(appName, envPath, envOnly, options);
+}
+
+/**
+ * @param {import('commander').Command} program
+ * @returns {void}
+ */
+function setupResolveCommand(program) {
+  program.command('resolve <app>')
+    .description('Generate .env from template; 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)')
+    .action(async(appName, options) => {
+      try {
+        await runResolveAppAction(appName, options);
+      } catch (error) {
+        handleCommandError(error, 'resolve');
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { setupResolveCommand };

package/lib/cli/setup-utility.js

@@ -10,11 +10,11 @@ const { formatSuccessParagraph } = require('../utils/cli-test-layout-chalk');
 const path = require('path');
 const fs = require('fs');
 const chalk = require('chalk');
-const secrets = require('../core/secrets');
 const generator = require('../generator');
 const logger = require('../utils/logger');
 const { handleCommandError, logOfflinePathWhenType } = require('../utils/cli-utils');
 const { detectAppType, getDeployJsonPath, getResolveAppPath } = require('../utils/paths');
+const { setupResolveCommand } = require('./setup-utility-resolve');
 
 const JSON_HELP_AFTER = `
 Example:
@@ -46,6 +46,8 @@ Examples:
 
   $ 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.
 `;
 
 /**
@@ -119,46 +121,20 @@ function logSplitJsonResult(result) {
   }
 }
 
-function setupResolveCommand(program) {
-  program.command('resolve <app>')
-    .description('Generate .env from template; optional validate after')
-    .option('-f, --force', 'Generate missing secret keys in secrets file')
-    .option('--skip-validation', 'Skip file validation after generating .env')
-    .action(async(appName, options) => {
-      try {
-        const { appPath, envOnly } = await getResolveAppPath(appName);
-        const envPath = await secrets.generateEnvFile(
-          appName,
-          undefined,
-          'docker',
-          options.force,
-          { appPath, envOnly, skipOutputPath: false, preserveFromPath: null }
-        );
-        logger.log(`✔ Generated .env file: ${envPath}`);
-        if (envOnly) {
-          logger.log(chalk.gray('  (env-only mode: validation skipped; no application config file)'));
-        } else if (!options.skipValidation) {
-          const validate = require('../validation/validate');
-          const result = await validate.validateAppOrFile(appName);
-          validate.displayValidationResults(result);
-          if (!result.valid) {
-            logger.log(chalk.yellow('\n⚠  Validation found errors. Fix them before deploying.'));
-            process.exit(1);
-          }
-        }
-      } catch (error) {
-        handleCommandError(error, 'resolve');
-        process.exit(1);
-      }
-    });
-}
-
 function setupJsonCommand(program) {
   program.command('json <app>')
     .description('Write deployment JSON to disk for version control')
     .addHelpText('after', JSON_HELP_AFTER)
     .action(async(appName, options) => {
       try {
+        const resolved = await getResolveAppPath(appName);
+        const { emitManifestMetadataLineIfTTY } = require('../utils/manifest-source-emit');
+        emitManifestMetadataLineIfTTY(logger, {
+          appKey: appName,
+          appPath: resolved.appPath,
+          envOnly: resolved.envOnly,
+          json: false
+        });
         const result = await generator.generateDeployJsonWithValidation(appName, options);
         if (result.success) {
           const fileName = result.path.includes('application-schema.json') ? 'application-schema.json' : 'deployment JSON';
@@ -193,50 +169,93 @@ function setupSplitJsonCommand(program) {
     });
 }
 
+function buildRepairExternalIntegrationOptions(appName, options, format) {
+  const all = options.all === true;
+  return {
+    auth: options.auth,
+    doc: options.doc || all,
+    dryRun: options.dryRun,
+    format,
+    rbac: options.rbac || all,
+    expose: options.expose || all,
+    sync: options.sync || all,
+    api: options.api || all,
+    test: options.test || all,
+    backup: options.backup,
+    noBackup: options.noBackup
+  };
+}
+
+function logRepairResult(options, result) {
+  if (options.dryRun && result.updated && result.changes.length > 0) {
+    logger.log(chalk.yellow('\nWould apply:'));
+    result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
+    return;
+  }
+  if (Array.isArray(result.backupPaths) && result.backupPaths.length > 0) {
+    result.backupPaths.forEach((p) => logger.log(chalk.gray(`Backup: ${p}`)));
+  }
+  if (result.updated) {
+    logger.log(formatSuccessParagraph('Repaired external integration config.'));
+    return;
+  }
+  if (Array.isArray(result.changes) && result.changes.length > 0) {
+    logger.log(formatSuccessParagraph('Repair actions completed.'));
+    result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
+    return;
+  }
+  if (result.readmeRegenerated) {
+    logger.log(formatSuccessParagraph('Regenerated README.md from deployment manifest.'));
+    return;
+  }
+  logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
+}
+
+/**
+ * Handler for `aifabrix repair <systemKey>`.
+ * @param {string} appName
+ * @param {object} options - Commander options
+ * @returns {Promise<void>}
+ */
+async function handleRepairCommand(appName, options) {
+  const { repairExternalIntegration } = require('../commands/repair');
+  const { detectAppType } = require('../utils/paths');
+  const { appPath } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
+  let format = 'yaml';
+  try {
+    const config = require('../core/config');
+    format = (await config.getFormat()) || format;
+  } catch (_) {
+    /* default yaml when config unavailable */
+  }
+  const result = await repairExternalIntegration(
+    appName,
+    buildRepairExternalIntegrationOptions(appName, options, format)
+  );
+  logRepairResult(options, result);
+}
+
 function setupRepairCommand(program) {
   program.command('repair <systemKey>')
     .description('Fix external integration drift (files, RBAC, manifest, …)')
+    .option('--all', 'Run all repair actions (api, doc, expose, rbac, sync, test)')
+    .option(
+      '--api',
+      'Validate and sync API contracts needed for OpenAPI/MCP (uses local OpenAPI specs at integration/<systemKey>/openapi/*.json when present)'
+    )
     .option('--auth <method>', 'Set authentication method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none); updates system file and env.template')
     .option('--doc', 'Regenerate README.md from deployment manifest')
-    .option('--dry-run', 'Report changes only; do not write')
-    .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
     .option('--expose', 'Set exposed.schema on each datasource from all fieldMappings.attributes keys (metadata.<key>); removes deprecated exposed.attributes if present')
+    .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist')
     .option('--sync', 'Add default sync section to datasources that lack it')
     .option('--test', 'Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes')
+    .option('--no-backup', 'Skip timestamped copies under integration/<systemKey>/backup/')
+    .option('--dry-run', 'Report changes only; do not write')
     .addHelpText('after', REPAIR_HELP_AFTER)
     .action(async(appName, options) => {
       try {
-        const { repairExternalIntegration } = require('../commands/repair');
-        const { detectAppType } = require('../utils/paths');
-        const { appPath } = await detectAppType(appName);
-        logOfflinePathWhenType(appPath);
-        let format = 'yaml';
-        try {
-          const config = require('../core/config');
-          format = (await config.getFormat()) || format;
-        } catch (_) {
-          // use default yaml when config unavailable
-        }
-        const result = await repairExternalIntegration(appName, {
-          auth: options.auth,
-          doc: options.doc,
-          dryRun: options.dryRun,
-          format,
-          rbac: options.rbac,
-          expose: options.expose,
-          sync: options.sync,
-          test: options.test
-        });
-        if (options.dryRun && result.updated && result.changes.length > 0) {
-          logger.log(chalk.yellow('\nWould apply:'));
-          result.changes.forEach(c => logger.log(chalk.gray(`  ${c}`)));
-        } else if (result.updated) {
-          logger.log(formatSuccessParagraph('Repaired external integration config.'));
-        } else if (result.readmeRegenerated) {
-          logger.log(formatSuccessParagraph('Regenerated README.md from deployment manifest.'));
-        } else {
-          logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
-        }
+        await handleRepairCommand(appName, options);
       } catch (error) {
         handleCommandError(error, 'repair');
         process.exit(1);
@@ -308,28 +327,56 @@ function setupSplitJsonConvertShowCommands(program) {
   setupShowCommand(program);
 }
 
-async function runValidateCommand(appOrFile, options) {
-  const validate = require('../validation/validate');
-  const opts = options.opts ? options.opts() : options;
+function emitManifestAfterValidateIfApplicable(appOrFile, result, outFormat) {
+  if (outFormat === 'json' || !result?.appPath || !appOrFile || typeof appOrFile !== 'string') {
+    return;
+  }
+  try {
+    if (fs.existsSync(appOrFile) && fs.statSync(appOrFile).isFile()) {
+      return;
+    }
+    const { emitManifestMetadataLineIfTTY } = require('../utils/manifest-source-emit');
+    emitManifestMetadataLineIfTTY(logger, {
+      appKey: appOrFile,
+      appPath: result.appPath,
+      envOnly: false,
+      json: false
+    });
+  } catch {
+    /* ignore emit failures */
+  }
+}
+
+async function runValidateBatchBranch(validate, opts) {
   const integration = opts.integration === true;
   const builder = opts.builder === true;
+  if (!integration && !builder) {
+    return false;
+  }
   const outFormat = (opts.format || 'default').toLowerCase();
+  const batchResult = integration && builder
+    ? await validate.validateAll(opts)
+    : integration
+      ? await validate.validateAllIntegrations(opts)
+      : await validate.validateAllBuilderApps(opts);
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify(batchResult, null, 2));
+  } else {
+    validate.displayBatchValidationResults(batchResult);
+  }
+  if (!batchResult.valid) process.exit(1);
+  return true;
+}
 
-  if (integration || builder) {
-    const batchResult = integration && builder
-      ? await validate.validateAll(opts)
-      : integration
-        ? await validate.validateAllIntegrations(opts)
-        : await validate.validateAllBuilderApps(opts);
-    if (outFormat === 'json') {
-      logger.log(JSON.stringify(batchResult, null, 2));
-    } else {
-      validate.displayBatchValidationResults(batchResult);
-    }
-    if (!batchResult.valid) process.exit(1);
+async function runValidateCommand(appOrFile, options) {
+  const validate = require('../validation/validate');
+  const opts = options.opts ? options.opts() : options;
+  if (await runValidateBatchBranch(validate, opts)) {
     return;
   }
 
+  const outFormat = (opts.format || 'default').toLowerCase();
+
   if (!appOrFile || typeof appOrFile !== 'string') {
     logger.log(chalk.red('App name or file path is required, or use --integration / --builder'));
     process.exit(1);
@@ -339,8 +386,20 @@ async function runValidateCommand(appOrFile, options) {
     ...opts,
     certSync: opts.certSync === true
   });
+  emitManifestAfterValidateIfApplicable(appOrFile, result, outFormat);
   if (outFormat === 'json') {
-    logger.log(JSON.stringify(result, null, 2));
+    let payload = result;
+    try {
+      if (result?.appPath && appOrFile && typeof appOrFile === 'string') {
+        if (!(fs.existsSync(appOrFile) && fs.statSync(appOrFile).isFile())) {
+          const { getManifestSourcePayload } = require('../utils/manifest-source-emit');
+          payload = { ...result, manifestSource: getManifestSourcePayload(appOrFile, result.appPath) };
+        }
+      }
+    } catch {
+      /* keep plain result */
+    }
+    logger.log(JSON.stringify(payload, null, 2));
   } else {
     validate.displayValidationResults(result);
   }