@aifabrix/builder 2.45.0 → 2.46.0

package/lib/commands/protection-cli-leaves.js

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview Protection subcommand registration (keeps setupProtectionCommands under line limit).
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { resolveProtectionArgument } = require('../protection/resolve');
+const {
+  runProtectionValidate,
+  runProtectionUpload,
+  runProtectionList,
+  runProtectionShow,
+  runProtectionDelete
+} = require('../protection/run-commands');
+const { runProtectionCreate } = require('../protection/run-protection-create');
+
+const SHARED_OPTS = [
+  ['-e, --env <environment>', 'Environment key'],
+  ['-v, --verbose', 'Verbose output']
+];
+
+const PROTECTION_CREATE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection create hubspot-companies --type country-sales
+  $ aifabrix protection create hr-persons --type department-manager
+  $ aifabrix protection create erp-projects --type project-team
+  $ aifabrix protection create hubspot-companies --dimension-key country --dry-run
+  $ aifabrix protection create hubspot-companies --type country-sales --force
+
+Preset types:
+  country-sales, department-manager, customer-team, project-team, static-region, owner-direct
+`;
+
+const PROTECTION_VALIDATE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection validate hubspot-companies
+  $ aifabrix protection validate hubspot-companies --simulate
+  $ aifabrix protection validate hubspot-companies --warnings-as-errors
+  $ aifabrix protection validate hubspot-companies --json
+`;
+
+const PROTECTION_UPLOAD_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection upload hubspot-companies
+  $ aifabrix protection upload hubspot-companies --dry-run
+  $ aifabrix protection upload hubspot-companies --no-sync
+`;
+
+const PROTECTION_LIST_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection list
+  $ aifabrix protection list --page 1 --page-size 50
+  $ aifabrix protection list --filter enabled:eq:true
+  $ aifabrix protection list --json
+`;
+
+const PROTECTION_SHOW_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection show hubspot-companies
+  $ aifabrix protection show hubspot-companies -v
+  $ aifabrix protection show hubspot-companies --json
+`;
+
+const PROTECTION_DELETE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection delete hubspot-companies
+  $ aifabrix protection delete hubspot-companies --yes
+`;
+
+/**
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ * @param {string} description
+ * @param {Function} action
+ * @param {Array<[string, string]>} extraOpts
+ * @param {string} helpAfter
+ */
+function addProtectionLeaf(cmd, name, description, action, extraOpts = [], helpAfter = '') {
+  const leaf = cmd.command(name).description(description);
+  for (const [flags, desc] of [...SHARED_OPTS, ...extraOpts]) {
+    leaf.option(flags, desc);
+  }
+  if (helpAfter) {
+    leaf.addHelpText('after', helpAfter);
+  }
+  leaf.action(async(datasourceKey, options) => {
+    try {
+      const code = await action(datasourceKey, options);
+      if (code && code !== 0) process.exit(code);
+    } catch (err) {
+      const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+      logger.error(formatBlockingError(err.message || String(err)));
+      process.exit(1);
+    }
+  });
+}
+
+/**
+ * @param {import('commander').Command} protection
+ */
+function registerProtectionCreate(protection) {
+  const leaf = protection
+    .command('create <datasourceKey>')
+    .description(
+      'Probe dataplane datasource + Controller dimension, then scaffold under integration/.protection/'
+    );
+  for (const [flags, desc] of SHARED_OPTS) {
+    leaf.option(flags, desc);
+  }
+  leaf
+    .option('--type <type>', 'Preset type (country-sales, department-manager, customer-team, project-team, static-region, owner-direct)')
+    .option('--dimension-key <key>', 'Dimension catalog key (inferred from --type when omitted)')
+    .option('--field <name>', 'Metadata field used by preset value templates when needed')
+    .option('--fk-name <name>', 'FK binding name in expressions (default: same as dimension key)')
+    .option('--protection-key <key>', 'metadata.key (default: <datasource>-<dimension>-access)')
+    .option('--display-name <text>', 'metadata.displayName')
+    .option('--rule-key <key>', 'Rule key inside spec.rules[0]')
+    .option('--principal-expression <expr>', 'Group principal expression (default: Sales {{fk.<fk>.metadata.iso3}} Users)')
+    .option('--value-expression <expr>', 'Grant valueExpression (default: {{fk.<fk>.metadata.iso2}})')
+    .option('--dry-run', 'Print YAML to stdout; do not write file')
+    .option('--force', 'Overwrite existing integration/.protection/<datasourceKey> manifest')
+    .option('--disabled', 'Set spec.enabled to false', false)
+    .addHelpText('after', PROTECTION_CREATE_HELP_AFTER)
+    .action(async(datasourceKey, options) => {
+      try {
+        const code = await runProtectionCreate(datasourceKey, {
+          ...options,
+          dryRun: options.dryRun === true,
+          force: options.force === true,
+          verbose: options.verbose === true,
+          disabled: options.disabled === true
+        }, logger);
+        if (code && code !== 0) process.exit(code);
+      } catch (err) {
+        const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+        if (Array.isArray(err.probeLines)) {
+          for (const line of err.probeLines) {
+            logger.log(line);
+          }
+        }
+        logger.error(formatBlockingError(err.message || String(err)));
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} protection
+ */
+function registerProtectionValidate(protection) {
+  addProtectionLeaf(
+    protection,
+    'validate <datasourceKey>',
+    'Validate protection manifest (local schema + dataplane)',
+    async(datasourceKey, options) => {
+      const resolved = resolveProtectionArgument(datasourceKey);
+      return runProtectionValidate(resolved.datasourceKey, resolved.manifest, {
+        ...options,
+        manifestPath: resolved.manifestPath,
+        warningsAsErrors: options.warningsAsErrors === true,
+        simulate: options.simulate === true,
+        json: options.json === true,
+        verbose: options.verbose === true
+      }, logger);
+    },
+    [
+      ['--json', 'Output dataplane report as JSON'],
+      ['--warnings-as-errors', 'Pass strict=true to dataplane validate'],
+      ['--simulate', 'Run simulate after validate passes']
+    ],
+    PROTECTION_VALIDATE_HELP_AFTER
+  );
+}
+
+/**
+ * @param {import('commander').Command} protection
+ */
+function registerProtectionUpload(protection) {
+  addProtectionLeaf(
+    protection,
+    'upload <datasourceKey>',
+    'Validate and upload protection manifest to dataplane',
+    async(datasourceKey, options) => {
+      const resolved = resolveProtectionArgument(datasourceKey);
+      return runProtectionUpload(resolved.datasourceKey, resolved.manifest, {
+        ...options,
+        manifestPath: resolved.manifestPath,
+        warningsAsErrors: options.warningsAsErrors === true,
+        dryRun: options.dryRun === true,
+        noSync: options.noSync === true,
+        verbose: options.verbose === true
+      }, logger);
+    },
+    [
+      ['--dry-run', 'Validate only; no upload or sync'],
+      ['--no-sync', 'Skip datasource sync after upload']
+    ],
+    PROTECTION_UPLOAD_HELP_AFTER
+  );
+}
+
+/**
+ * @param {import('commander').Command} protection
+ */
+function registerProtectionList(protection) {
+  const leaf = protection.command('list').description('List deployed protection manifests on dataplane');
+  for (const [flags, desc] of SHARED_OPTS) {
+    leaf.option(flags, desc);
+  }
+  leaf
+    .option('--json', 'Output paginated list as JSON')
+    .option('--page <n>', 'Page (1-based)', (v) => parseInt(v, 10))
+    .option('--page-size <n>', 'Page size', (v) => parseInt(v, 10))
+    .option('--filter <expr>', 'Filter (e.g. enabled:eq:true)')
+    .addHelpText('after', PROTECTION_LIST_HELP_AFTER)
+    .action(async(options) => {
+      try {
+        const code = await runProtectionList(
+          {
+            ...options,
+            json: options.json === true,
+            verbose: options.verbose === true
+          },
+          logger
+        );
+        if (code && code !== 0) process.exit(code);
+      } catch (err) {
+        const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+        logger.error(formatBlockingError(err.message || String(err)));
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} protection
+ */
+function registerProtectionShow(protection) {
+  addProtectionLeaf(
+    protection,
+    'show <datasourceKey>',
+    'Show deployed protection state from dataplane',
+    async(datasourceKey, options) =>
+      runProtectionShow(datasourceKey, {
+        ...options,
+        json: options.json === true,
+        verbose: options.verbose === true
+      }, logger),
+    [['--json', 'Output merged manifest + status as JSON']],
+    PROTECTION_SHOW_HELP_AFTER
+  );
+}
+
+/**
+ * @param {import('commander').Command} protection
+ */
+function registerProtectionDelete(protection) {
+  addProtectionLeaf(
+    protection,
+    'delete <datasourceKey>',
+    'Delete deployed protection for datasource',
+    async(datasourceKey, options) =>
+      runProtectionDelete(datasourceKey, {
+        ...options,
+        yes: options.yes === true
+      }, logger),
+    [['--yes', 'Skip confirmation prompt']],
+    PROTECTION_DELETE_HELP_AFTER
+  );
+}
+
+module.exports = {
+  registerProtectionCreate,
+  registerProtectionValidate,
+  registerProtectionUpload,
+  registerProtectionList,
+  registerProtectionShow,
+  registerProtectionDelete
+};

package/lib/commands/protection.js

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Protection manifest CLI commands.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  registerProtectionCreate,
+  registerProtectionValidate,
+  registerProtectionUpload,
+  registerProtectionList,
+  registerProtectionShow,
+  registerProtectionDelete
+} = require('./protection-cli-leaves');
+
+const PROTECTION_HELP_AFTER = `
+
+Examples:
+  $ aifabrix protection create hubspot-companies --type country-sales
+  $ aifabrix protection validate hubspot-companies --simulate
+  $ aifabrix protection upload hubspot-companies --dry-run
+  $ aifabrix protection list
+  $ aifabrix protection show hubspot-companies
+  $ aifabrix protection delete hubspot-companies --yes
+
+Per-command help:  aifabrix protection <command> --help
+`;
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupProtectionCommands(program) {
+  const protection = program
+    .command('protection')
+    .description('Manage protection manifests in integration/.protection/ (repo root)')
+    .addHelpText('after', PROTECTION_HELP_AFTER);
+
+  registerProtectionCreate(protection);
+  registerProtectionValidate(protection);
+  registerProtectionUpload(protection);
+  registerProtectionList(protection);
+  registerProtectionShow(protection);
+  registerProtectionDelete(protection);
+}
+
+module.exports = {
+  setupProtectionCommands
+};

package/lib/commands/repair-auth-apply.js

@@ -0,0 +1,127 @@
+/**
+ * Repair --auth: canonical authentication blocks and bearerToken preset.
+ *
+ * Applies canonical authentication blocks for repair --auth.
+ *
+ * @fileoverview Repair authentication method application
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { buildAuthenticationFromMethod } = require('../external-system/generator');
+
+/** Repair CLI --auth values (normalized lowercase). */
+const ALLOWED_REPAIR_AUTH = [
+  'oauth2',
+  'aad',
+  'apikey',
+  'bearertoken',
+  'bearerkey',
+  'basic',
+  'queryparam',
+  'oidc',
+  'hmac',
+  'none'
+];
+
+const PRESERVED_VARIABLE_KEYS = ['baseUrl', 'testEndpoint'];
+
+/**
+ * @param {string} authOption - Raw --auth value
+ * @returns {string} Normalized lowercase auth option
+ */
+function normalizeRepairAuthOption(authOption) {
+  return String(authOption || '').trim().toLowerCase();
+}
+
+/**
+ * @param {string} authOption - Normalized --auth value
+ * @returns {boolean}
+ */
+function isAllowedRepairAuth(authOption) {
+  return ALLOWED_REPAIR_AUTH.includes(normalizeRepairAuthOption(authOption));
+}
+
+/**
+ * Builds authentication block for repair --auth.
+ * @param {string} systemKey - System key
+ * @param {string} authOption - Normalized repair auth (e.g. bearertoken, apikey)
+ * @returns {{ method: string, variables: Object, security: Object }}
+ */
+function buildAuthenticationForRepair(systemKey, authOption) {
+  const normalized = normalizeRepairAuthOption(authOption);
+  const schemaMethod =
+    normalized === 'queryparam'
+      ? 'queryParam'
+      : normalized === 'bearertoken' || normalized === 'bearerkey'
+        ? 'bearerToken'
+        : normalized;
+  return buildAuthenticationFromMethod(systemKey, schemaMethod);
+}
+
+/**
+ * Merges preserved connectivity fields from existing auth into template variables.
+ * @param {Object} mergedVariables - Target variables object (mutated)
+ * @param {Object} existingVars - Prior authentication.variables
+ */
+function mergePreservedAuthVariables(mergedVariables, existingVars) {
+  if (!existingVars || typeof existingVars !== 'object') return;
+  for (const key of PRESERVED_VARIABLE_KEYS) {
+    if (existingVars[key] !== undefined && existingVars[key] !== null) {
+      mergedVariables[key] = existingVars[key];
+    }
+  }
+}
+
+/**
+ * Human-readable label for repair change log.
+ * @param {string} authOption - Normalized repair auth
+ * @returns {string}
+ */
+function repairAuthChangeLabel(authOption) {
+  const normalized = normalizeRepairAuthOption(authOption);
+  if (normalized === 'bearertoken' || normalized === 'bearerkey') return 'bearerToken';
+  return normalized;
+}
+
+const MISSING_TEST_ENDPOINT_WARNING =
+  'authentication.variables.testEndpoint is missing for apikey/bearerToken auth — add a GET URL for credential/E2E tests (e.g. /crm/v3/objects/contacts?limit=1, or a path resolved against baseUrl).';
+
+/**
+ * Warn when apikey auth (including bearerToken preset) has no testEndpoint.
+ * @param {Object} authentication - authentication block on system file
+ * @param {string[]} warnings - Mutable warnings list
+ */
+function appendTestEndpointWarningIfMissing(authentication, warnings) {
+  const method = String(authentication?.method || '').toLowerCase();
+  if (method !== 'apikey' && method !== 'bearertoken') return;
+  const testEndpoint = String(authentication?.variables?.testEndpoint || '').trim();
+  if (testEndpoint) return;
+  if (warnings.includes(MISSING_TEST_ENDPOINT_WARNING)) return;
+  warnings.push(MISSING_TEST_ENDPOINT_WARNING);
+}
+
+/**
+ * Audit system authentication after repair (with or without --auth).
+ * @param {Object} systemParsed - Parsed system config
+ * @param {string[]} warnings - Mutable warnings list
+ */
+function auditRepairAuthenticationWarnings(systemParsed, warnings) {
+  const authentication = systemParsed?.authentication || systemParsed?.auth;
+  if (!authentication || typeof authentication !== 'object') return;
+  appendTestEndpointWarningIfMissing(authentication, warnings);
+}
+
+module.exports = {
+  ALLOWED_REPAIR_AUTH,
+  MISSING_TEST_ENDPOINT_WARNING,
+  normalizeRepairAuthOption,
+  isAllowedRepairAuth,
+  buildAuthenticationForRepair,
+  mergePreservedAuthVariables,
+  repairAuthChangeLabel,
+  appendTestEndpointWarningIfMissing,
+  auditRepairAuthenticationWarnings
+};

package/lib/commands/repair-changed-files.js

@@ -0,0 +1,41 @@
+/**
+ * Track integration files touched during repair for CLI summary output.
+ *
+ * @fileoverview Repair changed-file tracking
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * Ensures backup/repair context has changed-file buckets.
+ * @param {Object} ctx - Repair backup context
+ * @returns {{ changedFiles: string[], wouldChangeFiles: string[] }}
+ */
+function ensureChangedFileBuckets(ctx) {
+  if (!ctx) return { changedFiles: [], wouldChangeFiles: [] };
+  if (!Array.isArray(ctx.changedFiles)) ctx.changedFiles = [];
+  if (!Array.isArray(ctx.wouldChangeFiles)) ctx.wouldChangeFiles = [];
+  return { changedFiles: ctx.changedFiles, wouldChangeFiles: ctx.wouldChangeFiles };
+}
+
+/**
+ * Records a file path that repair wrote or would write (dry-run).
+ * @param {string} filePath - Path to file
+ * @param {Object} ctx - Repair context with dryRun, changedFiles, wouldChangeFiles
+ */
+function trackRepairWrite(filePath, ctx) {
+  if (!filePath || !ctx) return;
+  const abs = path.resolve(filePath);
+  const { changedFiles, wouldChangeFiles } = ensureChangedFileBuckets(ctx);
+  const bucket = ctx.dryRun ? wouldChangeFiles : changedFiles;
+  if (!bucket.includes(abs)) bucket.push(abs);
+}
+
+module.exports = {
+  ensureChangedFileBuckets,
+  trackRepairWrite
+};

package/lib/commands/repair-datasource-keys.js

@@ -16,6 +16,7 @@ const path = require('path');
 const fs = require('fs');
 const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
 const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const { trackRepairWrite } = require('./repair-changed-files');
 
 /**
  * Returns suffix from a canonical-format filename: <systemKey>-datasource-<suffix>.<ext>.
@@ -174,8 +175,9 @@ function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey
 
     if (parsed.key !== canonicalKey) {
       parsed.key = canonicalKey;
+      const fullPath = path.join(appPath, fileName);
+      trackRepairWrite(fullPath, backupCtx);
       if (!dryRun) {
-        const fullPath = path.join(appPath, fileName);
         backupIntegrationFile(fullPath, backupCtx);
         writeConfigFile(fullPath, parsed);
       }
@@ -185,6 +187,7 @@ function normalizeDatasourceKeysAndFilenames(appPath, datasourceFiles, systemKey
     if (fileName !== canonicalFileName) {
       const oldPath = path.join(appPath, fileName);
       const newPath = path.join(appPath, canonicalFileName);
+      trackRepairWrite(newPath, backupCtx);
       if (!dryRun && fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
         backupIntegrationFile(oldPath, backupCtx);
         fs.renameSync(oldPath, newPath);

package/lib/commands/repair-datasource-run.js

@@ -0,0 +1,59 @@
+/**
+ * Batch datasource file repair during external integration repair.
+ *
+ * @fileoverview Run repairDatasourceFile across integration datasource files
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
+const { backupIntegrationFile } = require('../utils/integration-file-backup');
+const { trackRepairWrite } = require('./repair-changed-files');
+const { repairDatasourceFile } = require('./repair-datasource');
+
+/**
+ * @param {string} appPath
+ * @param {string[]} datasourceFiles
+ * @param {Object} options
+ * @param {boolean} dryRun
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function runDatasourceRepairs(appPath, datasourceFiles, options, dryRun, changes) {
+  if (!datasourceFiles || datasourceFiles.length === 0) return false;
+  let updated = false;
+  for (const fileName of datasourceFiles) {
+    const filePath = path.join(appPath, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    try {
+      const parsed = loadConfigFile(filePath);
+      const { updated: fileUpdated, changes: fileChanges } = repairDatasourceFile(parsed, {
+        expose: options.expose,
+        sync: options.sync,
+        test: options.test
+      });
+      if (fileUpdated) {
+        updated = true;
+        fileChanges.forEach(c => changes.push(`${fileName}: ${c}`));
+        if (!dryRun) {
+          backupIntegrationFile(filePath, options.backupCtx);
+          writeConfigFile(filePath, parsed);
+        }
+        trackRepairWrite(filePath, options.backupCtx);
+      }
+    } catch (err) {
+      logger.log(chalk.yellow(`⚠ Could not repair datasource ${fileName}: ${err.message}`));
+    }
+  }
+  return updated;
+}
+
+module.exports = {
+  runDatasourceRepairs
+};