@aifabrix/builder 2.44.5 → 2.44.6

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.js

@@ -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.
 `;
 
 /**
@@ -193,50 +195,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);

package/lib/commands/datasource-capability-dimension-cli.js

@@ -0,0 +1,128 @@
+/**
+ * `datasource capability dimension` command registration.
+ *
+ * @fileoverview dimension binding CLI
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const {
+  formatBlockingError,
+  headerKeyValue,
+  infoLine,
+  formatSuccessLine,
+  colorRollupPrefixedLine
+} = require('../utils/cli-test-layout-chalk');
+const { runCapabilityDimension } = require('../datasource/capability/run-capability-dimension');
+const { printCapabilitySuccessFooter } = require('./datasource-capability-output');
+
+const CAP_DIMENSION_HELP = `
+Adds or replaces one root **dimensions.<key>** binding (metadata-only; no pipeline).
+
+Examples:
+  $ aifabrix datasource capability dimension test-e2e-hubspot-companies --dimension market --type local --field country
+  $ aifabrix datasource capability dimension test-e2e-hubspot-companies --dimension owner --type fk --via hubspotOwner:owner --actor email
+`;
+
+function parseVia(raw) {
+  const list = Array.isArray(raw) ? raw : [];
+  return list.map((x) => String(x).trim()).filter(Boolean);
+}
+
+function logDimensionValidationOutcome(result) {
+  logger.log(formatSuccessLine('Local validation passed'));
+  if (result.remoteValidation?.ok) {
+    logger.log(formatSuccessLine('Remote validation passed'));
+  } else {
+    logger.log(colorRollupPrefixedLine('⚠ Remote validation skipped (not authenticated)'));
+  }
+  if (Array.isArray(result.semanticWarnings) && result.semanticWarnings.length > 0) {
+    result.semanticWarnings.forEach((w) => logger.log(colorRollupPrefixedLine(`⚠ ${w}`)));
+  }
+  logger.log(formatSuccessLine('Dimension binding updated'));
+}
+
+/**
+ * @param {string} fileOrKey
+ * @param {object} options - Commander options
+ * @returns {Promise<void>}
+ */
+async function runDimensionAction(fileOrKey, options) {
+  const via = parseVia(options.via);
+
+  const result = await runCapabilityDimension({
+    fileOrKey,
+    dimension: options.dimension,
+    type: options.type,
+    field: options.field,
+    via,
+    actor: options.actor,
+    operator: options.operator,
+    required: options.required,
+    dryRun: Boolean(options.dryRun),
+    noBackup: Boolean(options.noBackup),
+    overwrite: Boolean(options.overwrite)
+  });
+
+  if (result.dryRun) {
+    logger.log(infoLine('Dry run — planned JSON Patch operations:'));
+    logger.log('');
+    logger.log(JSON.stringify(result.patchOperations, null, 2));
+    return;
+  }
+
+  logDimensionValidationOutcome(result);
+
+  if (result.backupPath) {
+    logger.log(headerKeyValue('Backup:', result.backupPath));
+  }
+  printCapabilitySuccessFooter(result.resolvedPath, result.updatedSections, 'Updated');
+}
+
+/**
+ * @param {import('commander').Command} cap
+ * @returns {void}
+ */
+function setupCapabilityDimensionCommand(cap) {
+  cap
+    .command('dimension <file-or-key>')
+    .description('Add or replace one root dimensions binding (local or FK-backed)')
+    .requiredOption('--dimension <key>', 'Dimension key (ABAC-facing key; underscores allowed)')
+    .requiredOption('--type <type>', 'local | fk')
+    .option('--field <name>', 'For type=local: normalized attribute name in metadataSchema.properties')
+    .option(
+      '--via <fk:dimension>',
+      'For type=fk: hop as <fkName>:<dimensionKey>; repeat for multi-hop traversal',
+      (value, prev) => {
+        const list = prev || [];
+        list.push(value);
+        return list;
+      },
+      []
+    )
+    .option('--actor <actor>', 'For type=fk: displayName | email | userId | groups | roles')
+    .option('--operator <op>', 'For type=fk: eq | in (default depends on actor)')
+    .option('--required', 'Set dimensions.<key>.required=true')
+    .option('--no-required', 'Set dimensions.<key>.required=false')
+    .option('--dry-run', 'Print JSON Patch operations; do not write')
+    .option('--overwrite', 'Replace existing dimensions.<key> binding')
+    .option('--no-backup', 'Skip backup copy under integration/<app>/backup/')
+    .addHelpText('after', CAP_DIMENSION_HELP)
+    .action(async(fileOrKey, options) => {
+      try {
+        await runDimensionAction(fileOrKey, options);
+      } catch (error) {
+        logger.error(formatBlockingError(`capability dimension failed: ${error.message}`));
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  setupCapabilityDimensionCommand,
+  runDimensionAction
+};
+

package/lib/commands/datasource-capability-output.js

@@ -0,0 +1,29 @@
+/**
+ * Shared success footer for datasource capability mutating commands.
+ *
+ * @fileoverview capability CLI output footer
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const logger = require('../utils/logger');
+const { formatBulletSection, formatNextActions } = require('../utils/cli-test-layout-chalk');
+
+/**
+ * @param {string} resolvedPath
+ * @param {string[]} updatedSections
+ * @param {string} [heading='Updated']
+ * @returns {void}
+ */
+function printCapabilitySuccessFooter(resolvedPath, updatedSections, heading = 'Updated') {
+  const display =
+    resolvedPath.includes(' ') ? `"${resolvedPath}"` : resolvedPath;
+  logger.log('');
+  logger.log(formatBulletSection(`${heading}:`, updatedSections));
+  logger.log('');
+  logger.log(formatNextActions([`aifabrix datasource validate ${display}`]));
+}
+
+module.exports = {
+  printCapabilitySuccessFooter
+};

package/lib/commands/datasource-capability-relate-cli.js

@@ -0,0 +1,140 @@
+/**
+ * `datasource capability relate` command registration.
+ *
+ * @fileoverview relate CLI
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const logger = require('../utils/logger');
+const {
+  formatBlockingError,
+  headerKeyValue,
+  infoLine,
+  formatSuccessLine,
+  colorRollupPrefixedLine
+} = require('../utils/cli-test-layout-chalk');
+const { runCapabilityRelate } = require('../datasource/capability/run-capability-relate');
+const { printCapabilitySuccessFooter } = require('./datasource-capability-output');
+
+const CAP_RELATE_HELP = `
+Adds or replaces one **foreignKeys[]** row (metadata-only; no pipeline). Optional **metadataSchema.properties** stub unless **--skip-metadata-property**.
+
+  $ aifabrix datasource capability relate hubspot-deals --relation-name company --to hubspot-companies --field companyId --target-field externalId
+`;
+
+function parseTargetFields(raw) {
+  const tf = raw;
+  if (Array.isArray(tf) && tf.length > 0) {
+    return tf.map((x) => String(x).trim()).filter(Boolean);
+  }
+  if (tf !== undefined && tf !== null && String(tf).trim()) {
+    return [String(tf).trim()];
+  }
+  return undefined;
+}
+
+function logRelateValidationOutcome(result, joinLeft, joinRight) {
+  logger.log(formatSuccessLine('Local validation passed'));
+  if (result.remoteValidation?.ok) {
+    logger.log(formatSuccessLine('Remote validation passed'));
+  } else {
+    logger.log(colorRollupPrefixedLine('⚠ Remote validation skipped (not authenticated)'));
+  }
+  if (Array.isArray(result.semanticWarnings) && result.semanticWarnings.length > 0) {
+    result.semanticWarnings.forEach((w) => logger.log(colorRollupPrefixedLine(`⚠ ${w}`)));
+  }
+  logger.log(formatSuccessLine(`Relation created: ${joinLeft} → ${joinRight}`));
+}
+
+/**
+ * @param {string} fileOrKey
+ * @param {object} options - Commander options
+ * @returns {Promise<void>}
+ */
+async function runRelateAction(fileOrKey, options) {
+  const fields = [];
+  if (options.field) {
+    fields.push(String(options.field).trim());
+  }
+  const targetFields = parseTargetFields(options.targetField);
+
+  const result = await runCapabilityRelate({
+    fileOrKey,
+    relationName: options.relationName,
+    targetDatasource: options.to,
+    fields,
+    targetFields,
+    required: options.required,
+    description: options.description,
+    dryRun: Boolean(options.dryRun),
+    noBackup: Boolean(options.noBackup),
+    overwrite: Boolean(options.overwrite),
+    addMetadataProperty: !options.skipMetadataProperty
+  });
+
+  if (result.dryRun) {
+    logger.log(infoLine('Dry run — planned JSON Patch operations:'));
+    logger.log('');
+    logger.log(JSON.stringify(result.patchOperations, null, 2));
+    return;
+  }
+
+  const joinLeft = fields.length === 1 ? fields[0] : 'fields';
+  const joinRight =
+    Array.isArray(targetFields) && targetFields.length === 1
+      ? `${options.to}.${targetFields[0]}`
+      : options.to;
+  logRelateValidationOutcome(result, joinLeft, joinRight);
+
+  if (result.backupPath) {
+    logger.log(headerKeyValue('Backup:', result.backupPath));
+  }
+  printCapabilitySuccessFooter(result.resolvedPath, result.updatedSections, 'Updated');
+}
+
+/**
+ * @param {import('commander').Command} cap
+ * @returns {void}
+ */
+function setupCapabilityRelateCommand(cap) {
+  cap
+    .command('relate <file-or-key>')
+    .description(
+      'Add or replace foreignKeys[] metadata (+ optional metadataSchema property for relation name)'
+    )
+    .requiredOption('--relation-name <name>', 'FK name (camelCase; unique per datasource)')
+    .requiredOption('--to <targetDatasource>', 'Target datasource key (cross-system JSON key)')
+    .requiredOption('--field <name>', 'Local normalized attribute (foreignKeys.fields[])')
+    .option('--description <text>', 'FK description (defaults to a generated description)')
+    .option('--required', 'Mark FK required (foreignKeys[].required=true)')
+    .option('--no-required', 'Mark FK optional (foreignKeys[].required=false)')
+    .option(
+      '--target-field <name>',
+      'Target join field(s); repeat flag for composite; omit to use runtime default (externalId)',
+      (value, prev) => {
+        const list = prev || [];
+        list.push(value);
+        return list;
+      },
+      []
+    )
+    .option('--dry-run', 'Print JSON Patch operations; do not write')
+    .option('--overwrite', 'Replace existing foreignKeys row with the same name')
+    .option('--skip-metadata-property', 'Do not add metadataSchema.properties.<relationName>')
+    .option('--no-backup', 'Skip backup copy under integration/<app>/backup/')
+    .addHelpText('after', CAP_RELATE_HELP)
+    .action(async(fileOrKey, options) => {
+      try {
+        await runRelateAction(fileOrKey, options);
+      } catch (error) {
+        logger.error(formatBlockingError(`capability relate failed: ${error.message}`));
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  setupCapabilityRelateCommand,
+  runRelateAction
+};