@aifabrix/builder 2.45.5 → 2.46.0

package/lib/cli/setup-platform.js

@@ -23,7 +23,7 @@ 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 no infra running: prompts for installation profile (dev = one password for infra + Keycloak + platform UI; pro = autogen or manual split passwords). Credentials are stored in admin-secrets.env (encrypted secure:// values), not in secrets.local.yaml unless you pass --syncAdminKv on up-infra. The admin email is saved in config.yaml for the next run. 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.
@@ -54,6 +54,11 @@ function registerSetup(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('--platform <mode>', 'Platform mode: single (direct ports) or full (Traefik front door + multi-env)')
+    .option('--installation <profile>', 'Installation profile: dev (one password) or pro (autogen/manual)')
+    .option('--pro-password-mode <mode>', 'Pro profile only: autogen or manual')
+    .option('--admin-email <email>', 'Admin email (non-interactive fresh install)')
+    .option('--admin-password <password>', 'Admin password for dev or pro manual-single (non-interactive)')
     .option('-y, --yes', 'Skip destructive confirmation prompts (re-install, wipe data, teardown)')
     .addHelpText('after', SETUP_HELP_AFTER)
     .action(async(options) => {

package/lib/cli/setup-secrets.js

@@ -10,6 +10,7 @@ const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
 const { handleCommandError } = require('../utils/cli-utils');
 const { handleSecretsSet } = require('../commands/secrets-set');
 const { handleSecretsList } = require('../commands/secrets-list');
+const { handleSecretsGet } = require('../commands/secrets-get');
 const { handleSecretsRemove } = require('../commands/secrets-remove');
 const { handleSecretsValidate } = require('../commands/secrets-validate');
 const { handleSecure } = require('../commands/secure');
@@ -18,7 +19,7 @@ const logger = require('../utils/logger');
 
 const SECRET_GROUP_HELP_AFTER = `
 Subcommands:
-  list, set, remove, remove-all   User secrets.local.yaml (add --shared for shared/remote)
+  list, get, set, remove, remove-all   User secrets.local.yaml (add --shared for shared/remote)
   set-secrets-file      Point config at a shared secrets file or https URL
   validate              YAML structure (+ optional --naming)
 
@@ -38,6 +39,17 @@ Examples:
 Shared over https: key BASH_NPM_TOKEN --shared → NPM_TOKEN available in terminal (exported).
 `;
 
+const SECRET_GET_HELP_AFTER = `
+Examples:
+  $ aifabrix secret get hubspot-demo/token --shared --exists
+  $ aifabrix secret get myapp/clientSecret
+  $ aifabrix secret get hubspot/apiKey --shared --json
+
+  --exists   Script mode: exit 0 when the key is present and non-empty; no output.
+  Default      Local user secrets.local.yaml only (same target as secret set without --shared).
+  --shared     aifabrix-secrets store only (team file or remote API; same as secret set --shared).
+`;
+
 const SECRET_LIST_HELP_AFTER = `
 Examples:
   $ aifabrix secret list
@@ -168,6 +180,25 @@ function setupSecureCommand(program) {
     });
 }
 
+function setupSecretGetCommand(secretCmd) {
+  secretCmd
+    .command('get <key>')
+    .description('Get one secret (local user file by default; --shared for team store; --exists for scripts)')
+    .addHelpText('after', SECRET_GET_HELP_AFTER)
+    .option('--shared', 'Read from shared secrets (config aifabrix-secrets or remote API)')
+    .option('--exists', 'Exit 0 when key is present and non-empty; print nothing (for scripts)')
+    .option('--json', 'Output JSON { key, exists, value }')
+    .action(async(key, options) => {
+      try {
+        await config.ensureSecretsEncryptionKey();
+        await handleSecretsGet(key, options);
+      } catch (error) {
+        handleCommandError(error, 'secret get');
+        process.exit(1);
+      }
+    });
+}
+
 function setupSecretListCommand(secretCmd) {
   secretCmd
     .command('list')
@@ -196,6 +227,7 @@ function setupSecretsCommands(program) {
     .addHelpText('after', SECRET_GROUP_HELP_AFTER);
 
   setupSecretListCommand(secretCmd);
+  setupSecretGetCommand(secretCmd);
 
   secretCmd
     .command('set <key> <value>')

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

@@ -26,8 +26,11 @@ Examples:
   $ aifabrix repair hubspot-demo --dry-run
     Show what would change without writing files.
 
+  $ aifabrix repair hubspot-demo --auth bearerToken
+    Private-app style apikey: Authorization + Bearer prefix; preserves baseUrl/testEndpoint when present. Warns if testEndpoint is missing.
+
   $ aifabrix repair hubspot-demo --auth oauth2
-    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, basic, …).
+    Set authentication method; updates the system file and env.template (oauth2, aad, apikey, bearerToken, basic, …).
 
   $ aifabrix repair hubspot-demo --rbac --expose --sync --test
     Optional datasource fixes: RBAC roles/permissions, exposed.schema from attributes, default sync block, testPayload stubs.
@@ -38,8 +41,25 @@ Examples:
   Before overwriting files, repair writes timestamped backups under integration/<systemKey>/backup/ (same as datasource capability copy). Use --no-backup to skip.
 `;
 
+const RESOLVE_HELP_AFTER = `
+Examples:
+  $ aifabrix resolve hubspot-demo
+    External integration: resolves integration/<systemKey>/env.template to .env using local host ports (no Docker rewrite).
+
+  $ aifabrix resolve dataplane --fresh
+    Regenerate the full .env from env.template (no merge with an existing file). Use after adding many new variables or when a normal resolve did not pick up new template lines.
+
+  $ aifabrix secret set hubspot-demo/token "<your-token>"
+    Store a secret when resolve reports a missing kv:// reference.
+
+  If a key is not required by your system file, comment out its line in env.template instead of creating a secret.
+  $ aifabrix repair hubspot-demo
+    Align env.template with authentication.security and comment stale OAuth KV lines after --auth bearerToken.
+`;
+
 module.exports = {
   JSON_HELP_AFTER,
   VALIDATE_HELP_AFTER,
-  REPAIR_HELP_AFTER
+  REPAIR_HELP_AFTER,
+  RESOLVE_HELP_AFTER
 };

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

@@ -0,0 +1,198 @@
+/**
+ * `aifabrix repair` command wiring and CLI output (split from setup-utility for size limits).
+ *
+ * @fileoverview Repair CLI command
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError, logOfflinePathWhenType } = require('../utils/cli-utils');
+const { detectAppType } = require('../utils/paths');
+const { formatSuccessParagraph, formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { REPAIR_HELP_AFTER } = require('./setup-utility-help-after');
+
+/**
+ * @param {string} appName
+ * @param {object} options
+ * @param {string} format
+ * @returns {object}
+ */
+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
+  };
+}
+
+/**
+ * @param {string[]} changedFiles
+ * @param {boolean} dryRun
+ */
+function logRepairChangedFiles(changedFiles, dryRun) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return;
+  const title = dryRun ? '\nWould change files:' : '\nChanged files:';
+  logger.log(chalk.white(title));
+  changedFiles.forEach((filePath) => logger.log(chalk.cyan(`  ${filePath}`)));
+}
+
+/**
+ * @param {string[]} warnings
+ */
+function logRepairWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) return;
+  warnings.forEach((msg) => logger.log(formatWarningLine(msg)));
+}
+
+/**
+ * @param {string[]} changedFiles
+ * @param {string[]} warnings
+ */
+function logRepairNextActions(changedFiles, warnings) {
+  const hasFiles = Array.isArray(changedFiles) && changedFiles.length > 0;
+  const hasWarnings = Array.isArray(warnings) && warnings.length > 0;
+  if (!hasFiles && !hasWarnings) return;
+  logger.log(chalk.white('\nNext actions:'));
+  if (hasFiles) {
+    logger.log(chalk.gray('  • Open the paths above in your editor and review the diff'));
+    logger.log(chalk.gray('  • Run: aifabrix validate <systemKey>'));
+  }
+  if (hasWarnings) {
+    logger.log(chalk.gray('  • Fix warnings in the system file (especially authentication.variables.testEndpoint)'));
+    logger.log(chalk.gray('  • Run: aifabrix json <systemKey> && aifabrix upload <systemKey>'));
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {object} result
+ * @param {string[]} changedFiles
+ */
+function logRepairDryRunOutcome(options, result, changedFiles) {
+  logger.log(chalk.yellow('\nWould apply:'));
+  result.changes.forEach((c) => logger.log(chalk.gray(`  ${c}`)));
+  logRepairChangedFiles(changedFiles, true);
+  logRepairWarnings(result.warnings);
+  logRepairNextActions(changedFiles, result.warnings);
+}
+
+/**
+ * @param {object} result
+ * @param {string[]} changedFiles
+ */
+function logRepairSuccessOutcome(result, changedFiles) {
+  if (result.updated) {
+    logger.log(formatSuccessParagraph('Repaired external integration config.'));
+    logRepairChangedFiles(changedFiles, false);
+    logRepairNextActions(changedFiles, result.warnings);
+    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}`)));
+    logRepairChangedFiles(changedFiles, false);
+    logRepairNextActions(changedFiles, result.warnings);
+    return;
+  }
+  if (result.readmeRegenerated) {
+    logger.log(formatSuccessParagraph('Regenerated README.md from deployment manifest.'));
+    return;
+  }
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    logRepairNextActions(changedFiles, result.warnings);
+    return;
+  }
+  logger.log(chalk.gray('No changes needed; config already matches files on disk.'));
+}
+
+/**
+ * @param {object} options
+ * @param {object} result
+ */
+function logRepairResult(options, result) {
+  const changedFiles = result.changedFiles;
+  if (options.dryRun && result.updated && result.changes.length > 0) {
+    logRepairDryRunOutcome(options, result, changedFiles);
+    return;
+  }
+  if (Array.isArray(result.backupPaths) && result.backupPaths.length > 0) {
+    result.backupPaths.forEach((p) => logger.log(chalk.gray(`Backup: ${p}`)));
+  }
+  logRepairWarnings(result.warnings);
+  logRepairSuccessOutcome(result, changedFiles);
+}
+
+/**
+ * @param {string} appName
+ * @param {object} options
+ * @returns {Promise<void>}
+ */
+async function handleRepairCommand(appName, options) {
+  const { repairExternalIntegration } = require('../commands/repair');
+  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);
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+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, bearerToken, basic, queryParam, oidc, hmac, none); updates system file and env.template'
+    )
+    .option('--doc', 'Regenerate README.md from deployment manifest')
+    .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 {
+        await handleRepairCommand(appName, options);
+      } catch (error) {
+        handleCommandError(error, 'repair');
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  setupRepairCommand,
+  buildRepairExternalIntegrationOptions,
+  logRepairResult
+};

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

@@ -8,13 +8,18 @@
 
 'use strict';
 
+const path = require('path');
 const chalk = require('chalk');
 const secrets = require('../core/secrets');
+const secretsEnsure = require('../core/secrets-ensure');
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
 const coreConfig = require('../core/config');
+const pathsUtil = require('../utils/paths');
 const { resolvePreferLocalEnvOutputPathFlag } = require('../utils/applications-config-defaults');
 const { getResolveAppPath } = require('../utils/paths');
+const { resolveGenerateEnvEnvironment } = require('../utils/resolve-env-mode');
+const { RESOLVE_HELP_AFTER } = require('./setup-utility-help-after');
 
 /**
  * @param {string} appName
@@ -50,10 +55,17 @@ async function runResolveJsonOutput(appName, appPath, envOnly, envPath, options,
  * @param {string} envPath
  * @param {boolean} envOnly
  * @param {{ skipValidation?: boolean }} options
+ * @param {'local'|'docker'} environment
  * @returns {Promise<void>}
  */
-async function runResolveHumanOutput(appName, envPath, envOnly, options) {
+async function runResolveHumanOutput(appName, envPath, envOnly, options, environment) {
   logger.log(`✔ Generated .env file: ${envPath}`);
+  if (options.fresh) {
+    logger.log(chalk.gray('  Wrote full resolved content (--fresh; did not merge with an existing .env).'));
+  }
+  if (environment === 'local') {
+    logger.log(chalk.gray('  Resolved for local use (host ports; no Docker port rewrite).'));
+  }
   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) {
@@ -77,9 +89,26 @@ async function runResolveHumanOutput(appName, envPath, envOnly, options) {
  * @param {{ force?: boolean, skipValidation?: boolean, json?: boolean }} options
  * @returns {Promise<void>}
  */
+async function ensureResolveSecretsFromEnvTemplate(appPath, appName) {
+  const templatePath = path.join(appPath, 'env.template');
+  let emptyValuesForCredentials = false;
+  try {
+    const appType = await pathsUtil.detectAppType(appName);
+    emptyValuesForCredentials = appType?.baseDir === 'integration';
+  } catch {
+    emptyValuesForCredentials = false;
+  }
+  await secretsEnsure.ensureSecretsFromEnvTemplate(templatePath, {
+    preferredFilePath: pathsUtil.getPrimaryUserSecretsLocalPath(),
+    placeholderContext: secretsEnsure.buildInfraPlaceholderContext({}),
+    emptyValuesForCredentials
+  });
+}
+
 async function runResolveAppAction(appName, options) {
   const jsonMode = options.json === true;
   const { appPath, envOnly } = await getResolveAppPath(appName);
+  await ensureResolveSecretsFromEnvTemplate(appPath, appName);
   const manifestEmit = require('../utils/manifest-source-emit');
   manifestEmit.emitManifestMetadataLineIfTTY(logger, {
     appKey: appName,
@@ -89,24 +118,26 @@ async function runResolveAppAction(appName, options) {
   });
   const userCfg = await coreConfig.getConfig();
   const preferLocalEnvOutputPath = await resolvePreferLocalEnvOutputPathFlag(userCfg, appName);
+  const environment = resolveGenerateEnvEnvironment(appPath, appName);
   const envPath = await secrets.generateEnvFile(
     appName,
     undefined,
-    'docker',
+    environment,
     options.force,
     {
       appPath,
       envOnly,
       skipOutputPath: false,
       preserveFromPath: null,
-      preferLocalEnvOutputPath
+      preferLocalEnvOutputPath,
+      freshEnv: options.fresh === true
     }
   );
   if (jsonMode) {
     await runResolveJsonOutput(appName, appPath, envOnly, envPath, options, manifestEmit);
     return;
   }
-  await runResolveHumanOutput(appName, envPath, envOnly, options);
+  await runResolveHumanOutput(appName, envPath, envOnly, options, environment);
 }
 
 /**
@@ -116,7 +147,12 @@ async function runResolveAppAction(appName, options) {
 function setupResolveCommand(program) {
   program.command('resolve <appKey|systemKey>')
     .description('Generate .env from template (builder/<appKey>/ or integration/<systemKey>/); optional validate after')
+    .addHelpText('after', RESOLVE_HELP_AFTER)
     .option('-f, --force', 'Generate missing secret keys in secrets file')
+    .option(
+      '--fresh',
+      'Replace .env from env.template (no merge with existing .env or envOutputPath; same as deleting .env first)'
+    )
     .option('--skip-validation', 'Skip file validation after generating .env')
     .option('--json', 'Print JSON summary (envPath, manifestSource, optional validation)')
     .action(async(appName, options) => {

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

@@ -0,0 +1,197 @@
+/**
+ * `aifabrix validate` and `diff` command wiring (split from setup-utility for size limits).
+ *
+ * @fileoverview Validate and diff CLI commands
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { handleCommandError } = require('../utils/cli-utils');
+const { VALIDATE_HELP_AFTER } = require('./setup-utility-help-after');
+
+/**
+ * @param {string} appOrFile
+ * @param {object} result
+ * @param {string} outFormat
+ */
+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 */
+  }
+}
+
+/**
+ * @param {object} validate
+ * @param {object} opts
+ * @returns {Promise<boolean>}
+ */
+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;
+}
+
+/**
+ * @param {string} appOrFile
+ * @param {object} opts
+ * @returns {Promise<void>}
+ */
+async function runProtectionValidateBranch(appOrFile, opts) {
+  const { validateProtectionBatchCommand } = require('../protection/validate-batch');
+  const code = await validateProtectionBatchCommand(
+    {
+      env: opts.env,
+      json: (opts.format || '').toLowerCase() === 'json',
+      warningsAsErrors: opts.warningsAsErrors === true,
+      simulate: opts.simulate === true,
+      verbose: opts.verbose === true
+    },
+    logger
+  );
+  if (code !== 0) {
+    process.exit(code);
+  }
+}
+
+/**
+ * @param {object} result
+ * @param {string} appOrFile
+ * @returns {object}
+ */
+function buildValidateJsonPayload(result, appOrFile) {
+  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 */
+  }
+  return payload;
+}
+
+/**
+ * @param {string} appOrFile
+ * @param {object} result
+ * @param {string} outFormat
+ * @param {object} validate
+ */
+function displaySingleValidateResult(appOrFile, result, outFormat, validate) {
+  emitManifestAfterValidateIfApplicable(appOrFile, result, outFormat);
+  if (outFormat === 'json') {
+    logger.log(JSON.stringify(buildValidateJsonPayload(result, appOrFile), null, 2));
+    return;
+  }
+  validate.displayValidationResults(result);
+}
+
+/**
+ * @param {string} appOrFile
+ * @param {object} options
+ * @returns {Promise<void>}
+ */
+async function runValidateCommand(appOrFile, options) {
+  const validate = require('../validation/validate');
+  const opts = options.opts ? options.opts() : options;
+  const { isProtectionScope } = require('../protection/scope');
+  if (isProtectionScope(appOrFile)) {
+    await runProtectionValidateBranch(appOrFile, opts);
+    return;
+  }
+  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);
+  }
+  const result = await validate.validateAppOrFile(appOrFile, {
+    ...opts,
+    certSync: opts.certSync === true
+  });
+  displaySingleValidateResult(appOrFile, result, outFormat, validate);
+  if (!result.valid) process.exit(1);
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupValidateDiffCommands(program) {
+  program.command('validate [appKey|systemKey|file]')
+    .description('Validate appKey, systemKey, file path, .protection batch, or all under integration/ and builder/')
+    .addHelpText('after', VALIDATE_HELP_AFTER)
+    .option('--format <format>', 'Output format: json | default (human-readable)')
+    .option('--integration', 'Validate all applications under integration/')
+    .option('--builder', 'Validate all applications under builder/')
+    .option('--warnings-as-errors', 'For .protection: pass strict=true to dataplane validate')
+    .option('--simulate', 'For .protection: run simulate after validate')
+    .option(
+      '--cert-sync',
+      'After successful validation of an external integration, refresh the system file certification block from the dataplane (requires login)'
+    )
+    .action((appOrFile, options) => {
+      runValidateCommand(appOrFile, options).catch((error) => {
+        handleCommandError(error, 'validate');
+        process.exit(1);
+      });
+    });
+
+  program.command('diff <file1> <file2>')
+    .description('Diff two config files (optional schema validate)')
+    .option('--no-validate', 'Skip schema validation (type check still applied)')
+    .action(async(file1, file2, cmd) => {
+      try {
+        const diff = require('../core/diff');
+        const opts = cmd.opts();
+        const result = await diff.compareFiles(file1, file2, { validate: opts.validate !== false });
+        diff.formatDiffOutput(result);
+        if (!result.identical) process.exit(1);
+      } catch (error) {
+        handleCommandError(error, 'diff');
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  setupValidateDiffCommands,
+  runValidateCommand
+};