@aifabrix/builder 2.51.1 → 2.52.1

package/lib/integration-definition/apply.js

@@ -0,0 +1,478 @@
+/**
+ * Apply Builder Integration Definition to integration/<systemKey>/.
+ * @fileoverview Idempotent BID → package materialization (no AI)
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const fsp = require('fs').promises;
+const path = require('path');
+const { getIntegrationPath } = require('../utils/paths');
+const { validateIntegrationDefinition } = require('./validate');
+
+const STAMP_FILE = '.aifabrix-integration-definition.json';
+
+/**
+ * @param {string} dir
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+async function readStamp(dir) {
+  const stampPath = path.join(dir, STAMP_FILE);
+  try {
+    const raw = await fsp.readFile(stampPath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} bid
+ * @param {Record<string, unknown>} stamp
+ * @returns {void}
+ */
+function assertApplyAllowed(bid, stamp) {
+  if (!stamp) {
+    return;
+  }
+  const meta = /** @type {Record<string, unknown>} */ (bid.meta || {});
+  if (stamp.definitionId === bid.definitionId && stamp.definitionHash === bid.definitionHash) {
+    return;
+  }
+  if (stamp.definitionId === bid.definitionId) {
+    return;
+  }
+  if (stamp.systemKey === /** @type {any} */ (bid.packageIdentity).systemKey && !meta.replaceSystemKey) {
+    const err = new Error(
+      `systemKey ${stamp.systemKey} already bound to definitionId ${stamp.definitionId}; ` +
+        'set meta.replaceSystemKey true to replace'
+    );
+    err.code = 'BID_SYSTEM_KEY_CONFLICT';
+    throw err;
+  }
+}
+
+function buildDatasourceCapabilities(caps, key) {
+  return caps.map((capability) => ({
+    key: capability,
+    description: `${capability} ${key}`,
+    riskLevel:
+      capability === 'delete'
+        ? 'high'
+        : capability.startsWith('create') || capability.startsWith('update')
+          ? 'medium'
+          : 'low',
+    approvalRequired: false
+  }));
+}
+
+function buildDatasourceSchema(labelField) {
+  return {
+    metadataSchema: {
+      type: 'object',
+      properties: {
+        externalId: { type: 'string', index: true, description: 'Stable external join identity' },
+        id: { type: 'string', index: true, description: 'Vendor record id' },
+        [labelField]: { type: 'string', index: true, filter: true, description: 'Display label' }
+      },
+      required: ['externalId', 'id']
+    },
+    fieldMappings: {
+      attributes: {
+        id: { expression: '{{raw.id}}', description: 'Vendor record id' },
+        externalId: {
+          expression: '{{raw.id}}',
+          description: 'Stable join identity (defaults to vendor id until enrichment)'
+        },
+        [labelField]: {
+          expression: `{{raw.${labelField}}}`,
+          description: 'Display label (enrich from OpenAPI raw paths as needed)'
+        }
+      }
+    }
+  };
+}
+
+function enrichDatasourceFile(body, ds, enrichOptions) {
+  const { enrichDatasourceFromOpenApi } = require('./enrich-openapi-operations');
+  const openapiSourceRef =
+    (typeof ds.openapiSourceRef === 'string' && ds.openapiSourceRef.trim()) ||
+    (typeof enrichOptions.systemOpenapiSourceRef === 'string' &&
+      enrichOptions.systemOpenapiSourceRef.trim()) ||
+    '';
+  if (openapiSourceRef) {
+    enrichDatasourceFromOpenApi(body, openapiSourceRef, {
+      baseDir: enrichOptions.baseDir,
+      associationTargets: enrichOptions.associationTargets
+    });
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} ds
+ * @param {string} systemKey
+ * @param {Record<string, string[]>} capabilities
+ * @param {Record<string, unknown>} sync
+ * @returns {Record<string, unknown>}
+ */
+function buildDatasourceFile(ds, systemKey, capabilities, sync, enrichOptions = {}) {
+  const key = String(ds.key);
+  const caps = capabilities[key] || ds.capabilityKeys || ['list', 'get'];
+  const labelField = ds.labelField || 'name';
+  const { repairSyncOperationsFromCapabilities } = require('../commands/repair-datasource-sync-operations');
+  const { seedPropertyKeysOnDatasource } = require('./enrich-crm-field-mappings');
+  const body = {
+    key,
+    displayName: ds.displayName || key,
+    description: ds.description || `${ds.displayName || key} datasource`,
+    enabled: true,
+    systemKey,
+    entityType: ds.entityType || 'recordStorage',
+    resourceType: ds.resourceType,
+    version: '1.0.0',
+    capabilities: buildDatasourceCapabilities(caps, key),
+    // Schema sync is mode/schedule/batchSize only; BID sync.mode=incremental is operational intent.
+    sync: { mode: 'pull', schedule: /** @type {any} */ (sync).schedule || '0 */6 * * *', batchSize: 100 },
+    primaryKey: ['id'],
+    labelKey: [labelField],
+    ...buildDatasourceSchema(labelField)
+  };
+    // Mirror capabilities → openapi.operations + execution.cip.operations stubs (154.7).
+  repairSyncOperationsFromCapabilities(body, []);
+  seedPropertyKeysOnDatasource(body, ds.propertyKeys);
+  enrichDatasourceFile(body, ds, enrichOptions);
+  return body;
+}
+
+/**
+ * Collect vendor object-type segments from each datasource OpenAPI ref.
+ * Used so list/get can request associations to sibling collections.
+ * @param {any[]} datasources
+ * @param {string} systemOpenapiSourceRef
+ * @param {{ baseDir?: string }} enrichOptions
+ * @returns {string[]}
+ */
+function collectAssociationObjectTypes(datasources, systemOpenapiSourceRef, enrichOptions = {}) {
+  const {
+    loadOpenApiDocument,
+    indexOpenApiOperations,
+    objectTypeFromOpenApiPath
+  } = require('./enrich-openapi-operations');
+  const types = new Set();
+  for (const ds of datasources || []) {
+    // BID datasource keys are the named collection segments CRM association
+    // queries expect (opaque OpenAPI paths like /objects/0-3 omit these).
+    const dsKey = String(ds.key || '').trim();
+    if (dsKey) {
+      types.add(dsKey);
+    }
+    const ref =
+      (typeof ds.openapiSourceRef === 'string' && ds.openapiSourceRef.trim()) ||
+      systemOpenapiSourceRef ||
+      '';
+    if (!ref) {
+      continue;
+    }
+    try {
+      const doc = loadOpenApiDocument(ref, enrichOptions.baseDir);
+      const ops = indexOpenApiOperations(doc);
+      for (const op of ops) {
+        const objectType = objectTypeFromOpenApiPath(op.path);
+        if (objectType) {
+          types.add(objectType);
+        }
+      }
+    } catch {
+      // Skip unreadable refs; enrichment still binds per-datasource.
+    }
+  }
+  return [...types];
+}
+
+/**
+ * @param {Record<string, unknown>} bid
+ * @returns {Record<string, unknown>}
+ */
+function buildSystemFile(bid) {
+  const system = /** @type {Record<string, unknown>} */ (bid.system);
+  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
+  const refs = /** @type {Record<string, string>} */ (system.connectionRefs || {});
+  const tokenRef = refs.token || refs.apiKey || Object.values(refs)[0] || `kv://${identity.systemKey}/token`;
+  return {
+    key: system.key,
+    displayName: system.displayName || identity.displayName,
+    description: system.description || identity.displayName,
+    type: system.type || 'openapi',
+    enabled: true,
+    systemKind: system.systemKind || 'crm',
+    authentication: {
+      authType: 'credential',
+      credential: {
+        credentialKey: `${identity.systemKey}-cred`,
+        method: 'bearerToken',
+        variables: {
+          baseUrl: refs.baseUrl || 'https://example.invalid',
+          headerName: 'Authorization',
+          prefix: 'Bearer'
+        },
+        security: {
+          token: tokenRef
+        },
+        writeOnce: true
+      }
+    },
+    dataSources: (/** @type {any[]} */ (bid.datasources) || []).map((d) => d.key)
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} bid
+ * @param {string[]} datasourceFiles
+ * @param {string} systemFile
+ * @returns {Record<string, unknown>}
+ */
+function buildApplicationFile(bid, datasourceFiles, systemFile) {
+  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
+  return {
+    app: {
+      key: identity.systemKey,
+      displayName: identity.displayName,
+      description: `${identity.displayName} (BT BID-applied)`,
+      type: 'external'
+    },
+    externalIntegration: {
+      schemaBasePath: './',
+      systems: [systemFile],
+      dataSources: datasourceFiles,
+      autopublish: true,
+      version: identity.packageVersion
+    },
+    integrationDefinition: {
+      schemaName: bid.schemaName,
+      schemaVersion: bid.schemaVersion,
+      definitionId: bid.definitionId,
+      definitionHash: bid.definitionHash,
+      suiteRunId: /** @type {any} */ (bid.meta).suiteRunId
+    }
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} bid
+ * @returns {string}
+ */
+function buildEnvTemplate(bid) {
+  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
+  const systemKey = String(identity.systemKey);
+  const system = /** @type {Record<string, unknown>} */ (bid.system || {});
+  const refs = /** @type {Record<string, string>} */ (system.connectionRefs || {});
+  const tokenRef = refs.token || refs.apiKey || `kv://${systemKey}/token`;
+  return [
+    `# Environment for ${systemKey} (BID-applied). No plaintext secrets.`,
+    `# Resolve with aifabrix secret set ${systemKey}/token "<value>" --shared`,
+    `KV_TOKEN=${tokenRef}`,
+    ''
+  ].join('\n');
+}
+
+/**
+ * @param {Record<string, unknown>} bid
+ * @param {string} systemKey
+ * @returns {{
+ *   systemFile: string,
+ *   datasourceFiles: string[],
+ *   application: Record<string, unknown>,
+ *   system: Record<string, unknown>,
+ *   dsFiles: Array<{ name: string, body: Record<string, unknown> }>,
+ *   nextStamp: Record<string, unknown>
+ * }}
+ */
+function buildPackageArtifacts(bid, systemKey, enrichOptions = {}) {
+  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
+  const datasources = /** @type {Record<string, unknown>[]} */ (bid.datasources || []);
+  const capabilities = /** @type {Record<string, string[]>} */ (bid.capabilities || {});
+  const sync = /** @type {Record<string, unknown>} */ (bid.sync || {});
+  const system = /** @type {Record<string, unknown>} */ (bid.system || {});
+  const systemOpenapiSourceRef =
+    typeof system.openapiSourceRef === 'string' ? system.openapiSourceRef : '';
+  const associationTargets = collectAssociationObjectTypes(
+    datasources,
+    systemOpenapiSourceRef,
+    enrichOptions
+  );
+  const systemFile = `${systemKey}-system.json`;
+  const datasourceFiles = datasources.map((ds) => `${systemKey}-datasource-${ds.key}.json`);
+  return {
+    systemFile,
+    datasourceFiles,
+    application: buildApplicationFile(bid, datasourceFiles, systemFile),
+    system: buildSystemFile(bid),
+    dsFiles: datasources.map((ds) => ({
+      name: `${systemKey}-datasource-${ds.key}.json`,
+      body: buildDatasourceFile(ds, systemKey, capabilities, sync, {
+        ...enrichOptions,
+        systemOpenapiSourceRef,
+        associationTargets
+      })
+    })),
+    envTemplate: buildEnvTemplate(bid),
+    nextStamp: {
+      schemaName: bid.schemaName,
+      schemaVersion: bid.schemaVersion,
+      definitionId: bid.definitionId,
+      definitionHash: bid.definitionHash,
+      suiteRunId: /** @type {any} */ (bid.meta).suiteRunId,
+      systemKey,
+      packageVersion: identity.packageVersion,
+      appliedAt: new Date().toISOString()
+    }
+  };
+}
+
+/**
+ * @param {string} outDir
+ * @param {ReturnType<typeof buildPackageArtifacts>} artifacts
+ * @returns {Promise<void>}
+ */
+async function writePackageArtifacts(outDir, artifacts) {
+  await fsp.mkdir(outDir, { recursive: true });
+  await fsp.writeFile(
+    path.join(outDir, 'application.json'),
+    JSON.stringify(artifacts.application, null, 2),
+    'utf8'
+  );
+  await fsp.writeFile(
+    path.join(outDir, artifacts.systemFile),
+    JSON.stringify(artifacts.system, null, 2),
+    'utf8'
+  );
+  for (const file of artifacts.dsFiles) {
+    await fsp.writeFile(path.join(outDir, file.name), JSON.stringify(file.body, null, 2), 'utf8');
+  }
+  await fsp.writeFile(path.join(outDir, 'env.template'), artifacts.envTemplate, 'utf8');
+  await fsp.writeFile(
+    path.join(outDir, STAMP_FILE),
+    JSON.stringify(artifacts.nextStamp, null, 2),
+    'utf8'
+  );
+}
+
+/**
+ * @param {unknown} bidInput
+ * @returns {Record<string, unknown>}
+ */
+function requireValidBid(bidInput) {
+  const result = validateIntegrationDefinition(bidInput);
+  if (!result.valid) {
+    const err = new Error(`Invalid BID: ${result.errors.join('; ')}`);
+    err.code = 'BID_INVALID';
+    err.errors = result.errors;
+    throw err;
+  }
+  return result.bid;
+}
+
+/**
+ * @param {Record<string, unknown> | null} stamp
+ * @param {Record<string, unknown>} bid
+ * @param {string} outDir
+ * @param {string} systemKey
+ * @returns {Record<string, unknown> | null}
+ */
+function idempotentResult(stamp, bid, outDir, systemKey) {
+  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
+  if (
+    !(
+      stamp &&
+      stamp.definitionId === bid.definitionId &&
+      stamp.definitionHash === bid.definitionHash &&
+      fs.existsSync(path.join(outDir, 'application.json'))
+    )
+  ) {
+    return null;
+  }
+  return {
+    status: 'idempotent',
+    systemKey,
+    outputDir: outDir,
+    definitionId: bid.definitionId,
+    definitionHash: bid.definitionHash,
+    packageVersion: identity.packageVersion
+  };
+}
+
+/**
+ * Apply a validated BID to the integration workspace.
+ * @async
+ * @param {Record<string, unknown>} bidInput
+ * @param {{
+ *   outputDir?: string,
+ *   workspaceRoot?: string,
+ *   dryRun?: boolean,
+ *   force?: boolean,
+ *   openapiBaseDir?: string,
+ *   baseDir?: string
+ * }} [options]
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function applyIntegrationDefinition(bidInput, options = {}) {
+  const bid = requireValidBid(bidInput);
+  const identity = /** @type {Record<string, unknown>} */ (bid.packageIdentity);
+  const systemKey = String(identity.systemKey);
+  const outDir =
+    options.outputDir ||
+    (options.workspaceRoot
+      ? path.join(options.workspaceRoot, 'integration', systemKey)
+      : getIntegrationPath(systemKey));
+  const stamp = await readStamp(outDir);
+  const early = options.force ? null : idempotentResult(stamp, bid, outDir, systemKey);
+  if (early) {
+    return early;
+  }
+  assertApplyAllowed(bid, stamp);
+  // Prefer explicit openapiBaseDir; else ship-local enrichment specs (not caller cwd).
+  // Suite/builder-api apply runs with workspace cwd and must still resolve openapiSourceRef.
+  const defaultOpenapiBaseDir = path.join(__dirname, 'openapi-enrichment');
+  const artifacts = buildPackageArtifacts(bid, systemKey, {
+    baseDir: options.openapiBaseDir || options.baseDir || defaultOpenapiBaseDir
+  });
+  const fileList = [
+    'application.json',
+    artifacts.systemFile,
+    ...artifacts.datasourceFiles,
+    'env.template',
+    STAMP_FILE
+  ];
+  if (options.dryRun) {
+    return {
+      status: 'dryRun',
+      systemKey,
+      outputDir: outDir,
+      files: fileList,
+      stamp: artifacts.nextStamp
+    };
+  }
+  await writePackageArtifacts(outDir, artifacts);
+  return {
+    status: stamp ? 'updated' : 'created',
+    systemKey,
+    outputDir: outDir,
+    definitionId: bid.definitionId,
+    definitionHash: bid.definitionHash,
+    packageVersion: identity.packageVersion,
+    files: fileList
+  };
+}
+
+module.exports = {
+  applyIntegrationDefinition,
+  STAMP_FILE,
+  buildApplicationFile,
+  buildSystemFile,
+  buildDatasourceFile,
+  buildEnvTemplate
+};

package/lib/integration-definition/canonical-json.js

@@ -0,0 +1,51 @@
+/**
+ * Canonical JSON helpers for Builder Integration Definition hashing.
+ * @fileoverview Stable stringify for BID definitionHash
+ */
+
+'use strict';
+
+/**
+ * Recursively sort object keys for canonical JSON.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function sortValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortValue);
+  }
+  if (value && typeof value === 'object' && !(value instanceof Date)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = sortValue(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Canonical JSON string (sorted keys, no whitespace variance).
+ * @param {unknown} value
+ * @returns {string}
+ */
+function canonicalJsonString(value) {
+  return JSON.stringify(sortValue(value));
+}
+
+/**
+ * Clone BID without definitionHash for hashing.
+ * @param {Record<string, unknown>} bid
+ * @returns {Record<string, unknown>}
+ */
+function bidBodyWithoutHash(bid) {
+  const clone = { ...bid };
+  delete clone.definitionHash;
+  return clone;
+}
+
+module.exports = {
+  sortValue,
+  canonicalJsonString,
+  bidBodyWithoutHash
+};

package/lib/integration-definition/emit-suite-bid.js

@@ -0,0 +1,94 @@
+/**
+ * Stamp suite provenance onto a BID template for hard GP acceptance.
+ * @fileoverview Suite-emitted BID: suiteRunId + answerFingerprint + definitionHash
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { withDefinitionHash } = require('./hash');
+const { canonicalJsonString } = require('./canonical-json');
+
+/**
+ * Fingerprint discovery / case answers for BID meta.answerFingerprint.
+ * @param {unknown} answers
+ * @returns {string}
+ */
+function fingerprintAnswers(answers) {
+  const digest = crypto
+    .createHash('sha256')
+    .update(canonicalJsonString(answers === null || answers === undefined ? null : answers), 'utf8')
+    .digest('hex');
+  return `sha256:${digest}`;
+}
+
+function resolvePriorMeta(baseBid) {
+  return baseBid.meta && typeof baseBid.meta === 'object' && !Array.isArray(baseBid.meta)
+    ? baseBid.meta
+    : {};
+}
+
+function resolveAnswerFingerprint(options) {
+  if (typeof options.answerFingerprint === 'string' && options.answerFingerprint.trim()) {
+    return options.answerFingerprint.trim();
+  }
+  return fingerprintAnswers(options.answers);
+}
+
+function resolveProducedAt(options) {
+  if (typeof options.producedAt === 'string' && options.producedAt.trim()) {
+    return options.producedAt.trim();
+  }
+  return new Date().toISOString();
+}
+
+function resolveBtAssistantKey(options, priorMeta) {
+  if (typeof options.btAssistantKey === 'string' && options.btAssistantKey.trim()) {
+    return options.btAssistantKey.trim();
+  }
+  if (typeof priorMeta.btAssistantKey === 'string' && priorMeta.btAssistantKey.trim()) {
+    return priorMeta.btAssistantKey.trim();
+  }
+  return 'ra-business-transformation';
+}
+
+/**
+ * Clone a BID template and stamp suite provenance (hard GP).
+ * Does not invent datasources/capabilities — only meta + hash refresh.
+ *
+ * @param {Record<string, unknown>} baseBid - Valid BID template (e.g. example-bid.json)
+ * @param {Object} options
+ * @param {string} options.suiteRunId - Suite / processExecution id (required for hard GP)
+ * @param {string} [options.producedAt] - ISO timestamp
+ * @param {string} [options.btAssistantKey]
+ * @param {unknown} [options.answers] - Case answers for answerFingerprint
+ * @param {string} [options.answerFingerprint] - Explicit fingerprint override
+ * @returns {Record<string, unknown>}
+ */
+function emitSuiteBid(baseBid, options = {}) {
+  if (!baseBid || typeof baseBid !== 'object' || Array.isArray(baseBid)) {
+    throw new Error('emitSuiteBid requires a BID object');
+  }
+  const suiteRunId = String(options.suiteRunId || '').trim();
+  if (!suiteRunId) {
+    throw new Error('emitSuiteBid requires options.suiteRunId');
+  }
+  const priorMeta = resolvePriorMeta(baseBid);
+  const next = {
+    ...baseBid,
+    meta: {
+      ...priorMeta,
+      suiteRunId,
+      producedAt: resolveProducedAt(options),
+      btAssistantKey: resolveBtAssistantKey(options, priorMeta),
+      answerFingerprint: resolveAnswerFingerprint(options)
+    }
+  };
+  delete next.definitionHash;
+  return withDefinitionHash(next);
+}
+
+module.exports = {
+  emitSuiteBid,
+  fingerprintAnswers
+};