@aifabrix/builder 2.52.0 → 2.53.0

package/lib/integration-definition/from-discovery.js

@@ -0,0 +1,339 @@
+/**
+ * Compile a BID from discovery answer bindings (suite / Intent payload).
+ * @fileoverview Deterministic discovery → aifabrix.builder.integrationDefinition
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { emitSuiteBid } = require('./emit-suite-bid');
+
+const DEFAULT_GATES = [
+  'GP',
+  'G1',
+  'G2',
+  'G3',
+  'G4',
+  'G5',
+  'G6',
+  'G7',
+  'G8',
+  'G9',
+  'G10',
+  'G11',
+  'G12'
+];
+
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function unwrapBinding(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value) && 'value' in value) {
+    return /** @type {{ value: unknown }} */ (value).value;
+  }
+  return value;
+}
+
+/**
+ * Flatten suite answers / Intent structuredPayload into discovery bindings.
+ * @param {unknown} answersOrPayload
+ * @returns {Record<string, unknown>}
+ */
+function discoveryBindingsFromAnswers(answersOrPayload) {
+  if (Array.isArray(answersOrPayload)) {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const entry of answersOrPayload) {
+      if (!entry || typeof entry !== 'object') {
+        continue;
+      }
+      const when = /** @type {any} */ (entry).when;
+      const key = String((when && when.questionKey) || '').trim();
+      if (!key) {
+        continue;
+      }
+      const raw =
+        /** @type {any} */ (entry).value !== undefined
+          ? /** @type {any} */ (entry).value
+          : /** @type {any} */ (entry).answer;
+      out[key] = unwrapBinding(raw);
+    }
+    return out;
+  }
+  if (answersOrPayload && typeof answersOrPayload === 'object') {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, value] of Object.entries(answersOrPayload)) {
+      if (key.includes('.')) {
+        out[key] = unwrapBinding(value);
+      }
+    }
+    return out;
+  }
+  return {};
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @returns {string[]}
+ */
+function resolveApiGroups(bindings) {
+  const raw = bindings['system.apiGroups'];
+  if (Array.isArray(raw)) {
+    return raw.map((row) => String(row || '').trim()).filter(Boolean);
+  }
+  if (typeof raw === 'string' && raw.trim()) {
+    return [raw.trim()];
+  }
+  return [];
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @param {string[]} groups
+ * @param {Record<string, string>} openapiSourceRefs
+ * @returns {object[]}
+ */
+function buildDatasources(bindings, groups, openapiSourceRefs) {
+  const resourceTypes =
+    bindings['system.resourceTypes'] &&
+    typeof bindings['system.resourceTypes'] === 'object' &&
+    !Array.isArray(bindings['system.resourceTypes'])
+      ? /** @type {Record<string, unknown>} */ (bindings['system.resourceTypes'])
+      : {};
+  return groups.map((key) => {
+    const resourceType = String(resourceTypes[key] || key);
+    const openapiSourceRef =
+      (typeof openapiSourceRefs[key] === 'string' && openapiSourceRefs[key].trim()) ||
+      undefined;
+    const row = {
+      key,
+      displayName: key.charAt(0).toUpperCase() + key.slice(1),
+      entityType: 'recordStorage',
+      resourceType
+    };
+    if (openapiSourceRef) {
+      /** @type {any} */ (row).openapiSourceRef = openapiSourceRef;
+    }
+    const propertyKeys = bindings[`datasource.${key}.propertyKeys`];
+    if (Array.isArray(propertyKeys) && propertyKeys.length > 0) {
+      /** @type {any} */ (row).propertyKeys = propertyKeys
+        .map((item) => String(item || '').trim())
+        .filter(Boolean);
+    }
+    return row;
+  });
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @returns {object[]}
+ */
+function buildRelationships(bindings) {
+  const raw = bindings['system.relationships'];
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw
+    .filter((row) => row && typeof row === 'object')
+    .map((row) => ({
+      from: String(/** @type {any} */ (row).from || ''),
+      to: String(/** @type {any} */ (row).to || ''),
+      kind: String(/** @type {any} */ (row).kind || '')
+    }))
+    .filter((row) => row.from && row.to && row.kind);
+}
+
+/**
+ * @param {string[]} groups
+ * @param {Record<string, unknown>} bindings
+ * @returns {Record<string, string[]>}
+ */
+function buildCapabilities(groups, bindings) {
+  /** @type {Record<string, string[]>} */
+  const caps = {};
+  const named = String(bindings['system.namedWriteCapability'] || '').trim();
+  const [writeDs, writeCap] = named.includes('.')
+    ? named.split('.', 2)
+    : ['', ''];
+  for (const key of groups) {
+    const list = ['list', 'get'];
+    if (writeDs === key && writeCap) {
+      list.push(writeCap);
+      if (writeCap === 'createBasic') {
+        list.push('updateBasic', 'delete');
+      }
+    }
+    caps[key] = list;
+  }
+  return caps;
+}
+
+/**
+ * True when minimum discovery bindings exist for BID emission.
+ * @param {unknown} answersOrPayload
+ * @returns {boolean}
+ */
+function discoveryReadyForBid(answersOrPayload) {
+  const bindings = discoveryBindingsFromAnswers(answersOrPayload);
+  if (resolveApiGroups(bindings).length === 0) {
+    return false;
+  }
+  if (!bindings['system.syncMode']) {
+    return false;
+  }
+  const resourceTypes = bindings['system.resourceTypes'];
+  if (!resourceTypes || typeof resourceTypes !== 'object' || Array.isArray(resourceTypes)) {
+    return false;
+  }
+  return Object.keys(resourceTypes).length > 0;
+}
+
+/**
+ * @param {Record<string, unknown>} bindings
+ * @param {string} key
+ * @returns {Record<string, string>}
+ */
+function stringMapBinding(bindings, key) {
+  const raw = bindings[key];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return {};
+  }
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const [mapKey, value] of Object.entries(raw)) {
+    const trimmedKey = String(mapKey || '').trim();
+    const trimmedValue = String(value || '').trim();
+    if (trimmedKey && trimmedValue) {
+      out[trimmedKey] = trimmedValue;
+    }
+  }
+  return out;
+}
+
+function mergeStringMapRefs(fromBindings, fromOptions, fallback) {
+  if (fromOptions && typeof fromOptions === 'object') {
+    return { ...fromBindings, ...fromOptions };
+  }
+  if (Object.keys(fromBindings).length > 0) {
+    return fromBindings;
+  }
+  return fallback;
+}
+
+/**
+ * Compile BID from discovery bindings + package options.
+ * Builder-owned SSOT (not dataplane Runtime).
+ * @param {Object} options
+ * @param {unknown} [options.answers]
+ * @param {Record<string, unknown>} [options.bindings]
+ * @param {string} options.systemKey
+ * @param {string} [options.displayName]
+ * @param {string} [options.packageVersion]
+ * @param {string} [options.systemKind]
+ * @param {Record<string, string>} [options.connectionRefs]
+ * @param {Record<string, string>} [options.openapiSourceRefs]
+ * @param {string} options.suiteRunId
+ * @param {string} [options.definitionId]
+ * @param {string} [options.btAssistantKey]
+ * @param {string[]} [options.knowledgePackRefs]
+ * @returns {Record<string, unknown>}
+ */
+function resolveBidInputs(options) {
+  const systemKey = String(options.systemKey || '').trim();
+  const suiteRunId = String(options.suiteRunId || '').trim();
+  if (!systemKey) {
+    throw new Error('bidFromDiscovery requires systemKey');
+  }
+  if (!suiteRunId) {
+    throw new Error('bidFromDiscovery requires suiteRunId');
+  }
+  const bindings = {
+    ...discoveryBindingsFromAnswers(options.answers),
+    ...(options.bindings && typeof options.bindings === 'object' ? options.bindings : {})
+  };
+  if (!discoveryReadyForBid(bindings)) {
+    throw new Error('bidFromDiscovery requires complete discovery bindings');
+  }
+  return {
+    systemKey,
+    suiteRunId,
+    bindings,
+    groups: resolveApiGroups(bindings),
+    syncMode: String(bindings['system.syncMode'] || 'incremental').trim() || 'incremental',
+    displayName: String(options.displayName || '').trim() || systemKey,
+    openapiSourceRefs: mergeStringMapRefs(
+      stringMapBinding(bindings, 'system.openapiSourceRefs'),
+      options.openapiSourceRefs,
+      {}
+    ),
+    connectionRefs: mergeStringMapRefs(
+      stringMapBinding(bindings, 'system.connectionRefs'),
+      options.connectionRefs,
+      { token: `kv://${systemKey}/token` }
+    )
+  };
+}
+
+function buildDiscoveryBidDraft(options, inputs) {
+  const {
+    systemKey,
+    groups,
+    bindings,
+    syncMode,
+    displayName,
+    openapiSourceRefs,
+    connectionRefs
+  } = inputs;
+  const draft = {
+    schemaName: 'aifabrix.builder.integrationDefinition',
+    schemaVersion: '1.0.0',
+    definitionId:
+      String(options.definitionId || '').trim() || crypto.randomUUID(),
+    meta: {
+      suiteRunId: 'pending',
+      producedAt: new Date().toISOString(),
+      btAssistantKey: options.btAssistantKey || 'ra-business-transformation',
+      knowledgePackRefs: Array.isArray(options.knowledgePackRefs)
+        ? options.knowledgePackRefs
+        : ['role-assistant/ra-business-transformation/knowledge/']
+    },
+    packageIdentity: {
+      systemKey,
+      packageVersion: String(options.packageVersion || '0.1.0'),
+      displayName
+    },
+    system: {
+      key: systemKey,
+      displayName,
+      systemKind: String(options.systemKind || 'crm'),
+      type: 'openapi',
+      connectionRefs
+    },
+    datasources: buildDatasources(bindings, groups, openapiSourceRefs),
+    relationships: buildRelationships(bindings),
+    sync: { mode: syncMode, datasources: groups },
+    capabilities: buildCapabilities(groups, bindings),
+    authority: { writeRequiresUserAuthority: true },
+    acceptance: { gates: DEFAULT_GATES }
+  };
+  return draft;
+}
+
+function bidFromDiscovery(options = {}) {
+  const inputs = resolveBidInputs(options);
+  const draft = buildDiscoveryBidDraft(options, inputs);
+  return emitSuiteBid(draft, {
+    suiteRunId: inputs.suiteRunId,
+    btAssistantKey: draft.meta.btAssistantKey,
+    answers: options.answers || inputs.bindings
+  });
+}
+
+module.exports = {
+  bidFromDiscovery,
+  discoveryBindingsFromAnswers,
+  discoveryReadyForBid,
+  unwrapBinding
+};

package/lib/integration-definition/hash.js

@@ -0,0 +1,37 @@
+/**
+ * BID definitionHash helpers.
+ * @fileoverview SHA-256 hash for aifabrix.builder.integrationDefinition
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { canonicalJsonString, bidBodyWithoutHash } = require('./canonical-json');
+
+/**
+ * Compute definitionHash for a BID object (excludes definitionHash field).
+ * @param {Record<string, unknown>} bid
+ * @returns {string} sha256:<hex>
+ */
+function computeDefinitionHash(bid) {
+  const body = bidBodyWithoutHash(bid);
+  const digest = crypto.createHash('sha256').update(canonicalJsonString(body), 'utf8').digest('hex');
+  return `sha256:${digest}`;
+}
+
+/**
+ * Attach or refresh definitionHash on a BID object (mutates and returns).
+ * @param {Record<string, unknown>} bid
+ * @returns {Record<string, unknown>}
+ */
+function withDefinitionHash(bid) {
+  const next = { ...bid };
+  delete next.definitionHash;
+  next.definitionHash = computeDefinitionHash(next);
+  return next;
+}
+
+module.exports = {
+  computeDefinitionHash,
+  withDefinitionHash
+};

package/lib/integration-definition/index.js

@@ -0,0 +1,37 @@
+/**
+ * Builder Integration Definition (BID) public API.
+ * @fileoverview aifabrix.builder.integrationDefinition v1.0.0
+ */
+
+'use strict';
+
+const { applyIntegrationDefinition, STAMP_FILE } = require('./apply');
+const { computeDefinitionHash, withDefinitionHash } = require('./hash');
+const { emitSuiteBid, fingerprintAnswers } = require('./emit-suite-bid');
+const {
+  bidFromDiscovery,
+  discoveryBindingsFromAnswers,
+  discoveryReadyForBid
+} = require('./from-discovery');
+const {
+  validateIntegrationDefinition,
+  resetIntegrationDefinitionValidator,
+  INTEGRATION_DEFINITION_SCHEMA_NAME,
+  INTEGRATION_DEFINITION_SCHEMA_VERSION
+} = require('./validate');
+
+module.exports = {
+  applyIntegrationDefinition,
+  computeDefinitionHash,
+  withDefinitionHash,
+  emitSuiteBid,
+  fingerprintAnswers,
+  bidFromDiscovery,
+  discoveryBindingsFromAnswers,
+  discoveryReadyForBid,
+  validateIntegrationDefinition,
+  resetIntegrationDefinitionValidator,
+  INTEGRATION_DEFINITION_SCHEMA_NAME,
+  INTEGRATION_DEFINITION_SCHEMA_VERSION,
+  STAMP_FILE
+};

package/lib/integration-definition/resource-type-catalog.js

@@ -0,0 +1,59 @@
+/**
+ * Offline resource-type catalog keys for BID product rules (same SSOT as help topic).
+ * @fileoverview Active keys from docs/builder-help/resource-type-catalog.json
+ */
+
+'use strict';
+
+const { loadResourceTypeCatalog } = require('../programmatic/builder-help-governance');
+
+/** @type {Set<string>|null} */
+let cachedActiveKeys = null;
+
+/**
+ * @returns {Set<string>}
+ */
+function getActiveResourceTypeKeys() {
+  if (cachedActiveKeys) {
+    return cachedActiveKeys;
+  }
+  const catalog = loadResourceTypeCatalog();
+  const keys = new Set();
+  for (const row of catalog.resourceTypes || []) {
+    if (!row || typeof row !== 'object') {
+      continue;
+    }
+    const key = String(row.key || '').trim();
+    const status = String(row.status || 'active').trim().toLowerCase();
+    if (key && status === 'active') {
+      keys.add(key);
+    }
+  }
+  cachedActiveKeys = keys;
+  return cachedActiveKeys;
+}
+
+/**
+ * Reset cache (tests).
+ */
+function resetResourceTypeCatalogCache() {
+  cachedActiveKeys = null;
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isActiveResourceTypeKey(key) {
+  const normalized = String(key || '').trim();
+  if (!normalized) {
+    return false;
+  }
+  return getActiveResourceTypeKeys().has(normalized);
+}
+
+module.exports = {
+  getActiveResourceTypeKeys,
+  isActiveResourceTypeKey,
+  resetResourceTypeCatalogCache
+};

package/lib/integration-definition/system-kind-enum.js

@@ -0,0 +1,40 @@
+/**
+ * Enterprise systemKind enum shared with external-system.schema.json.
+ * @fileoverview Load allowed systemKind values for BID product rules
+ */
+
+'use strict';
+
+const externalSystemSchema = require('../schema/external-system.schema.json');
+
+/** @type {Set<string>|null} */
+let cachedKinds = null;
+
+/**
+ * @returns {Set<string>}
+ */
+function getAllowedSystemKinds() {
+  if (cachedKinds) {
+    return cachedKinds;
+  }
+  const values = externalSystemSchema?.properties?.systemKind?.enum;
+  cachedKinds = new Set(Array.isArray(values) ? values.map(String) : []);
+  return cachedKinds;
+}
+
+/**
+ * @param {string} kind
+ * @returns {boolean}
+ */
+function isAllowedSystemKind(kind) {
+  const normalized = String(kind || '').trim();
+  if (!normalized) {
+    return false;
+  }
+  return getAllowedSystemKinds().has(normalized);
+}
+
+module.exports = {
+  getAllowedSystemKinds,
+  isAllowedSystemKind
+};

package/lib/integration-definition/validate.js

@@ -0,0 +1,148 @@
+/**
+ * Validate Builder Integration Definition (BID) v1.0.0.
+ * @fileoverview AJV + hash + product rules for BID
+ */
+
+'use strict';
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const schema = require('../schema/integration-definition.schema.json');
+const { computeDefinitionHash } = require('./hash');
+const { isActiveResourceTypeKey } = require('./resource-type-catalog');
+const { isAllowedSystemKind } = require('./system-kind-enum');
+
+const GOLD_PATH_RE = /test-e2e-hubspot|knownPlatform|builder-hp-goal/i;
+
+let cachedValidator = null;
+
+/**
+ * @returns {import('ajv').ValidateFunction}
+ */
+function getValidator() {
+  if (cachedValidator) {
+    return cachedValidator;
+  }
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+  cachedValidator = ajv.compile(schema);
+  return cachedValidator;
+}
+
+/**
+ * Reset validator cache (tests).
+ */
+function resetIntegrationDefinitionValidator() {
+  cachedValidator = null;
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function appendAjvErrors(doc, errors) {
+  const validate = getValidator();
+  if (validate(doc)) {
+    return;
+  }
+  for (const err of validate.errors || []) {
+    errors.push(`${err.instancePath || '/'} ${err.message}`);
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function appendIdentityAndHashErrors(doc, errors) {
+  if (doc.schemaVersion !== '1.0.0') {
+    errors.push(`Unsupported schemaVersion ${String(doc.schemaVersion)}; expected 1.0.0`);
+  }
+  const expectedHash = computeDefinitionHash(doc);
+  if (doc.definitionHash !== expectedHash) {
+    errors.push(`definitionHash mismatch: expected ${expectedHash}`);
+  }
+  const identity = /** @type {Record<string, unknown>} */ (doc.packageIdentity || {});
+  const system = /** @type {Record<string, unknown>} */ (doc.system || {});
+  if (identity.systemKey && system.key && identity.systemKey !== system.key) {
+    errors.push('packageIdentity.systemKey must match system.key');
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function appendProductRuleErrors(doc, errors) {
+  const blob = JSON.stringify(doc);
+  if (GOLD_PATH_RE.test(blob)) {
+    errors.push(
+      'BID must not embed gold package paths or knownPlatform generation sources'
+    );
+  }
+  if (typeof doc.sync === 'object' && doc.sync && /** @type {any} */ (doc.sync).mode !== 'incremental') {
+    errors.push('sync.mode must be incremental');
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} doc
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function appendCatalogAndKindErrors(doc, errors) {
+  const system = /** @type {Record<string, unknown>} */ (doc.system || {});
+  if (system.systemKind !== undefined && system.systemKind !== null && system.systemKind !== '') {
+    if (!isAllowedSystemKind(String(system.systemKind))) {
+      errors.push(
+        `system.systemKind '${String(system.systemKind)}' is not an enterprise catalog value (see external-system.schema.json)`
+      );
+    }
+  }
+  const datasources = Array.isArray(doc.datasources) ? doc.datasources : [];
+  datasources.forEach((row, index) => {
+    if (!row || typeof row !== 'object') {
+      return;
+    }
+    const resourceType = /** @type {Record<string, unknown>} */ (row).resourceType;
+    if (resourceType === undefined || resourceType === null || resourceType === '') {
+      return;
+    }
+    const key = String(resourceType);
+    if (!isActiveResourceTypeKey(key)) {
+      errors.push(
+        `datasources[${index}].resourceType '${key}' is not an active catalog key (GET /help?topic=resourceTypeCatalog)`
+      );
+    }
+  });
+}
+
+/**
+ * @param {unknown} bid
+ * @returns {{ valid: true, bid: Record<string, unknown> } | { valid: false, errors: string[] }}
+ */
+function validateIntegrationDefinition(bid) {
+  const errors = [];
+  if (!bid || typeof bid !== 'object') {
+    return { valid: false, errors: ['BID must be an object'] };
+  }
+  const doc = /** @type {Record<string, unknown>} */ (bid);
+  appendAjvErrors(doc, errors);
+  appendIdentityAndHashErrors(doc, errors);
+  appendProductRuleErrors(doc, errors);
+  appendCatalogAndKindErrors(doc, errors);
+  if (errors.length) {
+    return { valid: false, errors };
+  }
+  return { valid: true, bid: doc };
+}
+
+module.exports = {
+  validateIntegrationDefinition,
+  resetIntegrationDefinitionValidator,
+  INTEGRATION_DEFINITION_SCHEMA_NAME: 'aifabrix.builder.integrationDefinition',
+  INTEGRATION_DEFINITION_SCHEMA_VERSION: '1.0.0'
+};