@aifabrix/builder 2.49.2 → 2.50.0

package/lib/commands/manifest-cli-integration-path.js

@@ -0,0 +1,63 @@
+/**
+ * Resolve on-disk integration path for manifest CLI (plan 141).
+ *
+ * @fileoverview cwd/integration → cwd/builder → ~/.aifabrix materialization
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { resolveApplicationManifestPathSync } = require('../utils/manifest-location');
+const { getIntegrationPath } = require('../utils/paths');
+const { findIntegrationPathAcrossWorkTree } = require('../utils/integration-path-resolve');
+const { discoverIntegrationFiles } = require('./repair-internal');
+
+/**
+ * @param {string} systemKey
+ * @returns {{ integrationPath: string, tier: string }}
+ */
+function resolveManifestCliIntegrationPath(systemKey) {
+  const manifestHit = resolveApplicationManifestPathSync({ targetKey: systemKey, mode: 'auto' });
+  if (manifestHit) {
+    return { integrationPath: manifestHit.absolutePath, tier: manifestHit.tier };
+  }
+
+  const fallback = getIntegrationPath(systemKey);
+  if (fs.existsSync(fallback)) {
+    const { systemFiles, datasourceFiles } = discoverIntegrationFiles(fallback);
+    if (systemFiles.length > 0 || datasourceFiles.length > 0) {
+      return { integrationPath: fallback, tier: 'paths-fallback' };
+    }
+  }
+
+  const workHit = findIntegrationPathAcrossWorkTree(systemKey);
+  if (workHit) {
+    return workHit;
+  }
+
+  const err = new Error(
+    `Integration "${systemKey}" not found. Looked under cwd/integration/${systemKey}/, ` +
+      'aifabrix-work sibling repos (*/integration/), and materialized ~/.aifabrix/.../integration/. ' +
+      'Run from the repo that contains the integration, set aifabrix-work, or set WORKSPACE_ROOT for builder-api workspaces.'
+  );
+  err.statusCode = 404;
+  throw err;
+}
+
+/**
+ * @param {string} integrationPath
+ * @param {string} systemKey
+ */
+function assertIntegrationPathMatchesSystemKey(integrationPath, systemKey) {
+  if (path.basename(path.resolve(integrationPath)) !== systemKey) {
+    throw new Error(`integrationPath must end with systemKey "${systemKey}"`);
+  }
+}
+
+module.exports = {
+  resolveManifestCliIntegrationPath,
+  assertIntegrationPathMatchesSystemKey
+};

package/lib/commands/manifest.js

@@ -0,0 +1,21 @@
+/**
+ * CLI manifest command group (plan 154.4).
+ *
+ * @fileoverview Thin wrapper registering manifest subcommands
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { registerManifestSubcommands } = require('./manifest-cli-commands');
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupManifestCommands(program) {
+  const manifest = program.command('manifest').description('Governed manifest section editing (get, patch, repair)');
+  registerManifestSubcommands(manifest);
+}
+
+module.exports = { setupManifestCommands };

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

@@ -47,7 +47,7 @@ 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
+  $ aifabrix protection upload hubspot-companies --sync
 `;
 
 const PROTECTION_LIST_HELP_AFTER = `
@@ -194,13 +194,13 @@ function registerProtectionUpload(protection) {
         manifestPath: resolved.manifestPath,
         warningsAsErrors: options.warningsAsErrors === true,
         dryRun: options.dryRun === true,
-        noSync: options.noSync === true,
+        sync: options.sync === true,
         verbose: options.verbose === true
       }, logger);
     },
     [
       ['--dry-run', 'Validate only; no upload or sync'],
-      ['--no-sync', 'Skip datasource sync after upload']
+      ['--sync', 'Force full datasource data sync after upload (default: bootstrap-if-empty)']
     ],
     PROTECTION_UPLOAD_HELP_AFTER
   );

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

@@ -27,7 +27,8 @@ const ALLOWED_REPAIR_AUTH = [
   'queryparam',
   'oidc',
   'hmac',
-  'none'
+  'none',
+  'bearerforward'
 ];
 
 const PRESERVED_VARIABLE_KEYS = ['baseUrl', 'testEndpoint'];
@@ -56,6 +57,9 @@ function isAllowedRepairAuth(authOption) {
  */
 function buildAuthenticationForRepair(systemKey, authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
+  if (normalized === 'bearerforward') {
+    return buildBearerForwardAuthentication();
+  }
   const schemaMethod =
     normalized === 'queryparam'
       ? 'queryParam'
@@ -65,6 +69,14 @@ function buildAuthenticationForRepair(systemKey, authOption) {
   return buildAuthenticationFromMethod(systemKey, schemaMethod);
 }
 
+/**
+ * Facade APIs that forward the caller Bearer token — no workspace kv secret.
+ * @returns {{ authType: 'none' }}
+ */
+function buildBearerForwardAuthentication() {
+  return { authType: 'none' };
+}
+
 /**
  * Merges preserved connectivity fields from existing auth into template variables.
  * @param {Object} mergedVariables - Target variables object (mutated)
@@ -87,6 +99,7 @@ function mergePreservedAuthVariables(mergedVariables, existingVars) {
 function repairAuthChangeLabel(authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
   if (normalized === 'bearertoken' || normalized === 'bearerkey') return 'bearerToken';
+  if (normalized === 'bearerforward') return 'bearerForward';
   return normalized;
 }
 
@@ -144,6 +157,7 @@ module.exports = {
   normalizeRepairAuthOption,
   isAllowedRepairAuth,
   buildAuthenticationForRepair,
+  buildBearerForwardAuthentication,
   mergePreservedAuthVariables,
   repairAuthChangeLabel,
   appendTestEndpointWarningIfMissing,

package/lib/commands/repair-authentications-454.js

@@ -0,0 +1,169 @@
+/**
+ * Repair authentications[] normalization for 454.0 webhooks/syncBridge.
+ *
+ * @fileoverview Normalize legacy authentication to authentications[] slots
+ */
+
+'use strict';
+
+const { migrateAuthenticationToNestedSchema } = require('../utils/authentication-shape');
+
+const AUTH_USAGE_API = 'api';
+const AUTH_USAGE_WEBHOOK_INBOUND = 'webhookInbound';
+const AUTH_USAGE_SYNC_EXECUTION = 'syncExecution';
+
+/**
+ * @param {string} systemKey
+ * @returns {object}
+ */
+function buildWebhookInboundAuthSlot(systemKey) {
+  const key = systemKey || 'system';
+  return {
+    key: 'webhookInbound',
+    usage: AUTH_USAGE_WEBHOOK_INBOUND,
+    authType: 'credential',
+    credential: {
+      credentialKey: `${key}-webhook-inbound`,
+      method: 'hmac',
+      variables: {
+        algorithm: 'sha256',
+        signatureHeader: 'X-Webhook-Signature',
+        timestampHeader: 'X-Webhook-Timestamp',
+        signaturePrefix: 'v0='
+      },
+      security: {
+        signingSecret: `kv://${key}/webhookInbound/signingSecret`
+      }
+    }
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {object}
+ */
+function buildSyncExecutionAuthSlot(systemKey) {
+  const key = systemKey || 'system';
+  return {
+    key: 'syncExecution',
+    usage: AUTH_USAGE_SYNC_EXECUTION,
+    authType: 'credential',
+    credential: {
+      credentialKey: `${key}-sync-execution`,
+      method: 'apikey',
+      variables: {
+        baseUrl: 'https://api.example.com',
+        headerName: 'X-API-Key',
+        testEndpoint: '/health'
+      },
+      security: {
+        apiKey: `kv://${key}/syncExecution/apiKey`
+      }
+    }
+  };
+}
+
+/**
+ * Normalize legacy authentication to authentications[] when missing.
+ * @param {object} systemJson - Parsed external system manifest
+ * @returns {{ changed: boolean, warnings: string[] }}
+ */
+function repairAuthenticationsArray(systemJson) {
+  const warnings = [];
+  if (!systemJson || typeof systemJson !== 'object') {
+    return { changed: false, warnings };
+  }
+
+  migrateAuthenticationToNestedSchema(systemJson);
+
+  const existing = systemJson.authentications;
+  if (Array.isArray(existing) && existing.length > 0) {
+    return { changed: false, warnings };
+  }
+
+  const legacy = systemJson.authentication;
+  if (!legacy || typeof legacy !== 'object') {
+    return { changed: false, warnings };
+  }
+
+  systemJson.authentications = [
+    {
+      key: 'default',
+      usage: AUTH_USAGE_API,
+      ...legacy
+    }
+  ];
+  warnings.push(
+    'Normalized legacy authentication to authentications[{key:default, usage:api}].'
+  );
+  return { changed: true, warnings };
+}
+
+/**
+ * Ensure webhook/sync auth slots exist when repair flags request them.
+ * @param {object} systemJson
+ * @param {{ authWebhook?: boolean, authSync?: boolean, systemKey: string, authMethod?: string }} options
+ * @returns {{ changed: boolean, warnings: string[] }}
+ */
+function ensureAuthUsageSlots(systemJson, options) {
+  const warnings = [];
+  const { repairAuthenticationsArray: normalize } = { repairAuthenticationsArray };
+  const base = normalize(systemJson);
+  warnings.push(...base.warnings);
+  let changed = base.changed;
+
+  if (!Array.isArray(systemJson.authentications)) {
+    systemJson.authentications = [];
+  }
+
+  const ensureSlot = (usage, slotKey, slotFactory) => {
+    const found = systemJson.authentications.some(
+      (row) => row && row.usage === usage
+    );
+    if (found) {
+      return;
+    }
+    if (typeof slotFactory === 'function') {
+      systemJson.authentications.push(slotFactory(options.systemKey));
+      warnings.push(`Added authentications slot usage=${usage} key=${slotKey}.`);
+      changed = true;
+      return;
+    }
+    const template = systemJson.authentications[0] || systemJson.authentication;
+    if (!template || typeof template !== 'object') {
+      warnings.push(`Cannot add ${usage} slot — no authentication template available.`);
+      return;
+    }
+    const { key: _ignored, usage: _u, ...rest } = template;
+    systemJson.authentications.push({ key: slotKey, usage, ...rest });
+    warnings.push(`Added authentications slot usage=${usage} key=${slotKey}.`);
+    changed = true;
+  };
+
+  if (options.authWebhook) {
+    ensureSlot(
+      AUTH_USAGE_WEBHOOK_INBOUND,
+      'webhookInbound',
+      buildWebhookInboundAuthSlot
+    );
+  }
+  if (options.authSync) {
+    ensureSlot(
+      AUTH_USAGE_SYNC_EXECUTION,
+      'syncExecution',
+      buildSyncExecutionAuthSlot
+    );
+  }
+
+  return { changed, warnings };
+}
+
+module.exports = {
+  repairAuthenticationsArray,
+  ensureAuthUsageSlots,
+  buildWebhookInboundAuthSlot,
+  buildSyncExecutionAuthSlot,
+  AUTH_USAGE_API,
+  AUTH_USAGE_WEBHOOK_INBOUND,
+  AUTH_USAGE_SYNC_EXECUTION
+};

package/lib/commands/repair-capability-openapi-warnings.js

@@ -0,0 +1,126 @@
+/**
+ * Warn when datasource capabilities lack matching openapi.operations (autoRbac).
+ *
+ * @fileoverview repair-capability-openapi-warnings
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { loadConfigFile } = require('../utils/config-format');
+const { capabilityKeysFromManifest } = require('./repair-datasource-sync-operations');
+
+/**
+ * @param {string} opKey
+ * @returns {string}
+ */
+function normalizeRbacOperationKey(opKey) {
+  const s = typeof opKey === 'string' ? opKey.trim() : '';
+  if (!s) return '';
+  if (/^[a-z][a-zA-Z0-9]*$/.test(s)) return s.toLowerCase();
+  const withHyphens = s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+  const cleaned = withHyphens.replace(/[^a-z0-9-]+/g, '-');
+  return cleaned.replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {boolean}
+ */
+function hasAutoRbacOpenApi(parsed) {
+  const openapi = parsed?.openapi;
+  return (
+    openapi &&
+    typeof openapi === 'object' &&
+    openapi.autoRbac === true &&
+    openapi.operations &&
+    typeof openapi.operations === 'object' &&
+    !Array.isArray(openapi.operations)
+  );
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {Set<string>}
+ */
+function normalizedOpenApiOperationKeys(parsed) {
+  const ops = parsed?.openapi?.operations;
+  const out = new Set();
+  if (!ops || typeof ops !== 'object') {
+    return out;
+  }
+  for (const key of Object.keys(ops)) {
+    const norm = normalizeRbacOperationKey(key) || key;
+    if (norm) out.add(norm);
+  }
+  return out;
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {string[]}
+ */
+function findCapabilityKeysMissingFromOpenApi(parsed) {
+  if (!hasAutoRbacOpenApi(parsed)) {
+    return [];
+  }
+  const capKeys = capabilityKeysFromManifest(parsed?.capabilities);
+  if (capKeys.length === 0) {
+    return [];
+  }
+  const openApiKeys = normalizedOpenApiOperationKeys(parsed);
+  return capKeys.filter((key) => !openApiKeys.has(normalizeRbacOperationKey(key) || key));
+}
+
+/**
+ * @param {string} fileName
+ * @param {Object} parsed
+ * @param {string[]} missingKeys
+ * @returns {string}
+ */
+function formatCapabilityOpenApiDriftWarning(fileName, parsed, missingKeys) {
+  const dsKey = typeof parsed?.key === 'string' && parsed.key.trim() ? parsed.key.trim() : fileName;
+  return (
+    `${dsKey}: capabilities declare ${missingKeys.join(', ')} but openapi.operations is missing them — ` +
+    'RBAC repair may omit matching permissions; operations sync runs automatically with --rbac'
+  );
+}
+
+/**
+ * @param {string} appPath
+ * @param {string[]} datasourceFiles
+ * @param {string[]} warnings
+ * @returns {number}
+ */
+function collectCapabilityOpenApiDriftWarnings(appPath, datasourceFiles, warnings) {
+  if (!Array.isArray(warnings) || !Array.isArray(datasourceFiles)) {
+    return 0;
+  }
+  let count = 0;
+  for (const fileName of datasourceFiles) {
+    const filePath = path.join(appPath, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    let parsed;
+    try {
+      parsed = loadConfigFile(filePath);
+    } catch {
+      continue;
+    }
+    const missingKeys = findCapabilityKeysMissingFromOpenApi(parsed);
+    if (missingKeys.length === 0) continue;
+    warnings.push(formatCapabilityOpenApiDriftWarning(fileName, parsed, missingKeys));
+    count += 1;
+  }
+  return count;
+}
+
+module.exports = {
+  normalizeRbacOperationKey,
+  hasAutoRbacOpenApi,
+  findCapabilityKeysMissingFromOpenApi,
+  collectCapabilityOpenApiDriftWarnings,
+  formatCapabilityOpenApiDriftWarning
+};

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

@@ -0,0 +1,135 @@
+/**
+ * Datasource repair orchestration (service contract, base/openapi/optional passes).
+ *
+ * @fileoverview Repair datasource file apply orchestration
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { repairOpenapiSection } = require('./repair-datasource-openapi');
+const { repairSyncOperationsFromCapabilities } = require('./repair-datasource-sync-operations');
+const { normalizeAutoRbacOperationKeys } = require('./repair-datasource-auto-rbac');
+const { repairTestPayload } = require('./repair-datasource-test-payload');
+const { repairComV2Manifest } = require('./repair-datasource-com-v2');
+const {
+  isDeprecatedNoneLlmManifest,
+  repairNoneLlmToServiceContract
+} = require('./repair-datasource-service-contract');
+const {
+  isDeprecatedNoneOpenapiHttpManifest,
+  repairNoneOpenapiHttpToServiceContract,
+  normalizeCipOpenapiRefs
+} = require('./repair-datasource-http-service-contract');
+const {
+  repairWebhookSection,
+  repairSyncBridgeSection,
+  collectWebhookSyncBridgeSystemWarnings
+} = require('./repair-datasource-webhooks-sync-bridge');
+
+/**
+ * @param {Object} parsed
+ * @param {Object} options
+ * @returns {boolean}
+ */
+function shouldApplyServiceContractRepair(parsed, options) {
+  return (
+    isDeprecatedNoneLlmManifest(parsed) ||
+    isDeprecatedNoneOpenapiHttpManifest(parsed) ||
+    (options.serviceContract && parsed?.resourceType === 'llm')
+  );
+}
+
+/**
+ * @param {Object} parsed
+ * @param {Object} options
+ * @param {boolean} none
+ * @param {string[]} changes
+ * @param {Object} helpers
+ * @returns {boolean}
+ */
+function applyOptionalDatasourceRepairs(parsed, options, none, changes, helpers) {
+  let updated = false;
+  if (options.operations) {
+    updated = repairSyncOperationsFromCapabilities(parsed, changes) || updated;
+  }
+  if (options.expose) {
+    updated = helpers.repairExposeFromAttributes(parsed, changes) || updated;
+  }
+  if (!none && options.sync) {
+    updated = helpers.repairSyncSection(parsed, changes) || updated;
+  }
+  if (options.test) {
+    helpers.sanitizeTestPayloadTopLevel(parsed, changes);
+    updated = repairTestPayload(parsed, changes) || updated;
+    updated = helpers.sanitizeTestPayloadTopLevel(parsed, changes) || updated;
+  }
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {boolean} none
+ * @param {string[]} changes
+ * @param {Object} [options]
+ * @param {Object} helpers
+ * @returns {boolean}
+ */
+function applyBaseDatasourceRepairs(parsed, none, changes, options, helpers) {
+  let updated = repairComV2Manifest(parsed, changes);
+  if (none) return updated;
+  updated = helpers.repairDimensionBindingShape(parsed, changes) || updated;
+  updated = helpers.repairRootDimensionsFromAttributes(parsed, changes) || updated;
+  updated = helpers.repairMetadataSchemaFromAttributes(parsed, changes) || updated;
+  const warnings = Array.isArray(options.warnings) ? options.warnings : [];
+  updated = repairWebhookSection(parsed, changes, warnings) || updated;
+  updated = repairSyncBridgeSection(parsed, changes, warnings) || updated;
+  collectWebhookSyncBridgeSystemWarnings(parsed, options.systemParsed, warnings);
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function applyOpenapiDatasourceRepairs(parsed, changes) {
+  let updated = false;
+  updated = repairOpenapiSection(parsed, changes) || updated;
+  updated = normalizeAutoRbacOperationKeys(parsed, changes) || updated;
+  return updated;
+}
+
+/**
+ * Runs all requested datasource repairs.
+ *
+ * @param {Object} parsed - Parsed datasource object (mutated)
+ * @param {Object} options - Repair flags
+ * @param {string[]} changes - Change log
+ * @param {Object} helpers - Functions from repair-datasource.js
+ * @returns {{ updated: boolean, changes: string[] }}
+ */
+function runRepairDatasourceFile(parsed, options, changes, helpers) {
+  const out = Array.isArray(changes) ? changes : [];
+  let updated = helpers.stripDeprecatedServiceCategory(parsed, out);
+
+  if (shouldApplyServiceContractRepair(parsed, options)) {
+    updated = repairNoneLlmToServiceContract(parsed, out) || updated;
+    updated = repairNoneOpenapiHttpToServiceContract(parsed, out) || updated;
+  }
+
+  updated = normalizeCipOpenapiRefs(parsed, out) || updated;
+
+  const none = helpers.isNoneEntityType(parsed?.entityType);
+
+  updated = applyBaseDatasourceRepairs(parsed, none, out, options, helpers) || updated;
+  updated = applyOpenapiDatasourceRepairs(parsed, out) || updated;
+  updated = applyOptionalDatasourceRepairs(parsed, options, none, out, helpers) || updated;
+
+  return { updated, changes: out };
+}
+
+module.exports = {
+  runRepairDatasourceFile
+};

package/lib/commands/repair-datasource-auto-rbac.js

@@ -120,12 +120,71 @@ function renameScenarioOperations(parsed, renameMap) {
   return updated;
 }
 
+/**
+ * @param {unknown} cap
+ * @param {string[]} caps
+ * @param {Object} renameMap
+ * @returns {boolean}
+ */
+function renameStringCapabilityKey(caps, cap, renameMap) {
+  if (typeof cap !== 'string') {
+    return false;
+  }
+  const newKey = renameMap[cap];
+  if (!newKey || newKey === cap) {
+    return false;
+  }
+  const idx = caps.indexOf(cap);
+  if (idx >= 0) {
+    caps[idx] = newKey;
+  }
+  return true;
+}
+
+/**
+ * @param {Object} cap
+ * @param {Object} renameMap
+ * @returns {boolean}
+ */
+function renameObjectCapabilityKey(cap, renameMap) {
+  if (!cap || typeof cap !== 'object') {
+    return false;
+  }
+  const k = safeString(cap.key);
+  if (!k) {
+    return false;
+  }
+  const newKey = renameMap[k];
+  if (!newKey || newKey === k) {
+    return false;
+  }
+  cap.key = newKey;
+  return true;
+}
+
 /**
  * When OpenAPI autoRbac is enabled, ensure operation keys are schema-valid and consistent across:
  * - openapi.operations
  * - execution.cip.operations
  * - testPayload.scenarios[].operation
  */
+function renameCapabilitiesKeys(parsed, renameMap, changes) {
+  const caps = parsed?.capabilities;
+  if (!Array.isArray(caps) || !renameMap || typeof renameMap !== 'object') {
+    return false;
+  }
+  let updated = false;
+  for (const cap of caps) {
+    if (renameStringCapabilityKey(caps, cap, renameMap) || renameObjectCapabilityKey(cap, renameMap)) {
+      updated = true;
+    }
+  }
+  if (updated && Array.isArray(changes)) {
+    changes.push('Aligned capabilities[].key with normalized autoRbac operation keys');
+  }
+  return updated;
+}
+
 function normalizeAutoRbacOperationKeys(parsed, changes) {
   const openapi = parsed?.openapi;
   if (!openapi || typeof openapi !== 'object') return false;
@@ -148,6 +207,7 @@ function normalizeAutoRbacOperationKeys(parsed, changes) {
   updated = renameKeysInObject(wsAllowed, renameMap) || updated;
   // If both alias + canonical exist, merge and drop alias (schema requires canonical camelCase keys).
   updated = mergeAndDeleteAliasKeys(wsAllowed, renameMap) || updated;
+  updated = renameCapabilitiesKeys(parsed, renameMap, changes) || updated;
 
   if (updated && Array.isArray(changes)) {
     const pairs = keysToRename.map((k) => `${k}→${renameMap[k]}`).join(', ');
@@ -161,6 +221,7 @@ function normalizeAutoRbacOperationKeys(parsed, changes) {
 
 module.exports = {
   normalizeAutoRbacOperationKeys,
-  toCamelCaseKey
+  toCamelCaseKey,
+  toKebabAliasKey
 };