@aifabrix/builder 2.44.4 → 2.44.6

package/lib/datasource/capability/relate-validate.js

@@ -0,0 +1,219 @@
+/**
+ * Semantic validation for `datasource capability relate`.
+ *
+ * Pure validation module: no CLI/auth logic.
+ *
+ * @fileoverview relate semantic validator
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} RelateLocalContext
+ * @property {any} sourceDoc
+ * @property {any|null} targetDocLocal
+ * @property {string} targetDatasourceKey
+ * @property {string[]} fields
+ * @property {string[]|undefined} targetFields
+ */
+
+/**
+ * @typedef {Object} RelateValidationInput
+ * @property {RelateLocalContext} localContext
+ * @property {any|null} remoteManifest - remote target datasource config (or null)
+ */
+
+/**
+ * @typedef {Object} RelateValidationResult
+ * @property {boolean} ok
+ * @property {string[]} errors
+ * @property {string[]} warnings
+ * @property {{ targetDoc: any|null, resolvedTargetFields: string[] }} resolved
+ */
+
+function _asObject(x) {
+  return x && typeof x === 'object' ? x : null;
+}
+
+function _getMetadataProp(doc, fieldName) {
+  const props = doc?.metadataSchema?.properties;
+  if (!props || typeof props !== 'object') return null;
+  const node = props[fieldName];
+  return _asObject(node);
+}
+
+function _getFieldMappingsAttributes(doc) {
+  const attrs = doc?.fieldMappings?.attributes;
+  return attrs && typeof attrs === 'object' ? attrs : null;
+}
+
+function _normalizeType(node) {
+  const t = node?.type;
+  if (typeof t === 'string') return t;
+  if (Array.isArray(t)) {
+    // common JSONSchema pattern: ["string","null"]
+    const nonNull = t.filter((x) => x && x !== 'null');
+    if (nonNull.length === 1 && typeof nonNull[0] === 'string') return nonNull[0];
+  }
+  return null;
+}
+
+function _isNullable(node) {
+  // dataplane uses `nullable: true` convention in config metadataSchema
+  return node?.nullable === true;
+}
+
+/**
+ * @param {RelateValidationInput} input
+ * @returns {RelateValidationResult}
+ */
+function validateRelateSemantics(input) {
+  const errors = [];
+  const warnings = [];
+  const local = input?.localContext;
+  const source = local?.sourceDoc;
+  const targetDatasourceKey = String(local?.targetDatasourceKey || '').trim();
+  const fields = Array.isArray(local?.fields) ? local.fields : [];
+  const resolvedTargetFields = _resolveTargetFields(local?.targetFields);
+
+  if (!_asObject(source)) {
+    errors.push('Local validation failed: sourceDoc missing or invalid.');
+    return { ok: false, errors, warnings, resolved: { targetDoc: null, resolvedTargetFields } };
+  }
+
+  const sourceAttrs = _getFieldMappingsAttributes(source);
+  const localFieldMeta = _validateSourceSide({ source, sourceAttrs, fields, errors });
+
+  const targetDoc = _resolveTargetDoc(local?.targetDocLocal, input?.remoteManifest);
+  if (!targetDoc) {
+    errors.push(
+      `Target datasource not found locally and remote validation did not provide a target config: ${targetDatasourceKey}`
+    );
+    return { ok: false, errors, warnings, resolved: { targetDoc: null, resolvedTargetFields } };
+  }
+
+  _validateJoinSemantics({
+    targetDoc,
+    targetDatasourceKey,
+    fields,
+    resolvedTargetFields,
+    localFieldMeta,
+    errors,
+    warnings
+  });
+
+  return { ok: errors.length === 0, errors, warnings, resolved: { targetDoc, resolvedTargetFields } };
+}
+
+function _resolveTargetFields(targetFieldsRaw) {
+  return Array.isArray(targetFieldsRaw) && targetFieldsRaw.length > 0
+    ? targetFieldsRaw.map((x) => String(x).trim()).filter(Boolean)
+    : ['externalId'];
+}
+
+function _resolveTargetDoc(targetDocLocal, remoteManifest) {
+  if (_asObject(targetDocLocal)) return targetDocLocal;
+  if (_asObject(remoteManifest)) return remoteManifest;
+  return null;
+}
+
+function _validateSourceSide({ source, sourceAttrs, fields, errors }) {
+  if (!fields || fields.length === 0) {
+    errors.push('Local validation failed: at least one local field is required.');
+    return {};
+  }
+  if (!sourceAttrs) {
+    errors.push('Source must declare fieldMappings.attributes (object).');
+  }
+
+  /** @type {Record<string, { type: string|null, nullable: boolean }>} */
+  const localFieldMeta = {};
+  for (const f of fields) {
+    const name = String(f || '').trim();
+    if (!name) {
+      errors.push('Local field names must be non-empty strings.');
+      continue;
+    }
+    if (sourceAttrs && !(name in sourceAttrs)) {
+      errors.push(`Source field not found in fieldMappings.attributes: ${name}`);
+    }
+    const node = _getMetadataProp(source, name);
+    if (!node) {
+      errors.push(`Source field not found in metadataSchema.properties: ${name}`);
+      continue;
+    }
+    localFieldMeta[name] = { type: _normalizeType(node), nullable: _isNullable(node) };
+  }
+  return localFieldMeta;
+}
+
+function _validateJoinSemantics({
+  targetDoc,
+  targetDatasourceKey,
+  fields,
+  resolvedTargetFields,
+  localFieldMeta,
+  errors,
+  warnings
+}) {
+  const targetAttrs = _getFieldMappingsAttributes(targetDoc);
+  if (!targetAttrs) {
+    warnings.push(`Target datasource is missing fieldMappings.attributes: ${targetDatasourceKey}`);
+  }
+
+  if (resolvedTargetFields.length !== fields.length) {
+    errors.push(
+      `Foreign key cardinality mismatch: ${fields.length} local field(s) vs ${resolvedTargetFields.length} target field(s).`
+    );
+    return;
+  }
+
+  for (let i = 0; i < fields.length; i += 1) {
+    _validateJoinFieldPair({
+      targetDoc,
+      targetDatasourceKey,
+      localName: String(fields[i] || '').trim(),
+      targetName: String(resolvedTargetFields[i] || '').trim(),
+      localFieldMeta,
+      errors,
+      warnings
+    });
+  }
+}
+
+function _validateJoinFieldPair({
+  targetDoc,
+  targetDatasourceKey,
+  localName,
+  targetName,
+  localFieldMeta,
+  errors,
+  warnings
+}) {
+  if (!targetName) {
+    errors.push('Target field names must be non-empty strings.');
+    return;
+  }
+  const targetNode = _getMetadataProp(targetDoc, targetName);
+  if (!targetNode) {
+    errors.push(`Target field not found in metadataSchema.properties: ${targetDatasourceKey}.${targetName}`);
+    return;
+  }
+  const lt = localFieldMeta[localName]?.type || null;
+  const tt = _normalizeType(targetNode);
+  if (lt && tt && lt !== tt) {
+    errors.push(`Type mismatch: ${localName} (${lt}) does not match ${targetDatasourceKey}.${targetName} (${tt}).`);
+  }
+  const ln = localFieldMeta[localName]?.nullable === true;
+  const tn = _isNullable(targetNode);
+  if (ln !== tn) {
+    warnings.push(`Nullable mismatch: ${localName} nullable=${ln} vs ${targetDatasourceKey}.${targetName} nullable=${tn}.`);
+  }
+}
+
+module.exports = {
+  validateRelateSemantics
+};
+

package/lib/datasource/capability/remove-operations.js

@@ -0,0 +1,275 @@
+/**
+ * Remove a capability from one datasource JSON document (including profile + testPayload cleanup).
+ *
+ * @fileoverview capability remove — inverse of copy
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { jsonPointerPath } = require('./json-pointer');
+const {
+  capabilityExists,
+  removeCapability,
+  deepClone
+} = require('./copy-operations');
+const {
+  resolveLogicalNameForRemove,
+  findMatchingOpsKeys,
+  resolveProfileKeyForLogical
+} = require('./capability-resolve');
+
+/**
+ * @param {unknown} capabilities
+ * @param {string} logicalName
+ * @returns {number} Index or -1
+ */
+function findCapabilityIndex(capabilities, logicalName) {
+  if (!Array.isArray(capabilities)) {
+    return -1;
+  }
+  return capabilities.findIndex(
+    (c) => String(c).toLowerCase() === String(logicalName).toLowerCase()
+  );
+}
+
+/**
+ * Planned RFC 6902 remove ops against `originalDoc` (before mutation). Paths use actual
+ * openapi/CIP object keys and scenario array indices (descending order for stability).
+ *
+ * @param {object} originalDoc
+ * @param {string} logicalName
+ * @param {string|undefined} openapiKey
+ * @param {string|undefined} cipKey
+ * @param {string|null} profileKey
+ * @returns {object[]}
+ */
+function buildRemovePatchOperations(originalDoc, logicalName, openapiKey, cipKey, profileKey) {
+  const ops = [];
+
+  const capIdx = findCapabilityIndex(originalDoc.capabilities, logicalName);
+  if (capIdx >= 0) {
+    ops.push({ op: 'remove', path: `/capabilities/${capIdx}` });
+  }
+
+  const ooPath = openapiKey ?? logicalName;
+  if (originalDoc.openapi?.operations?.[ooPath] !== undefined) {
+    ops.push({ op: 'remove', path: jsonPointerPath('openapi', 'operations', ooPath) });
+  }
+
+  const cipPath = cipKey ?? logicalName;
+  if (originalDoc.execution?.cip?.operations?.[cipPath] !== undefined) {
+    ops.push({ op: 'remove', path: jsonPointerPath('execution', 'cip', 'operations', cipPath) });
+  }
+
+  if (
+    profileKey !== null &&
+    profileKey !== undefined &&
+    originalDoc.exposed?.profiles?.[profileKey] !== undefined
+  ) {
+    ops.push({ op: 'remove', path: jsonPointerPath('exposed', 'profiles', profileKey) });
+  }
+
+  const aliases = new Set(
+    [logicalName, openapiKey, cipKey].filter((x) => x !== undefined && x !== null && x !== '')
+  );
+  pushScenarioRemovePatches(originalDoc, aliases, ops);
+
+  return ops;
+}
+
+/**
+ * @param {object} originalDoc
+ * @param {Set<string>} aliases
+ * @param {object[]} ops
+ * @returns {void}
+ */
+function pushScenarioRemovePatches(originalDoc, aliases, ops) {
+  const scenarios = originalDoc.testPayload?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return;
+  }
+  const idxs = [];
+  scenarios.forEach((s, i) => {
+    if (s && aliases.has(s.operation)) {
+      idxs.push(i);
+    }
+  });
+  idxs.sort((a, b) => b - a);
+  for (const i of idxs) {
+    ops.push({ op: 'remove', path: jsonPointerPath('testPayload', 'scenarios', String(i)) });
+  }
+}
+
+/**
+ * Drop testPayload.scenarios entries whose `operation` matches any alias (logical + openapi/cip keys).
+ *
+ * @param {object} doc - Mutated datasource
+ * @param {string} logicalKey - Canonical capability name
+ * @param {string|undefined} openapiKey - openapi.operations key removed
+ * @param {string|undefined} cipKey - cip.operations key removed
+ * @returns {boolean} True if the scenarios array changed
+ */
+function pruneTestPayloadScenarios(doc, logicalKey, openapiKey, cipKey) {
+  const scenarios = doc.testPayload?.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return false;
+  }
+  const aliases = new Set(
+    [logicalKey, openapiKey, cipKey].filter((x) => x !== undefined && x !== null && x !== '')
+  );
+  const next = scenarios.filter((s) => !s || !aliases.has(s.operation));
+  if (next.length === scenarios.length) {
+    return false;
+  }
+  doc.testPayload.scenarios = next;
+  return true;
+}
+
+/**
+ * Drop empty `testPayload.scenarios`, then remove `testPayload` when it becomes `{}`.
+ *
+ * @param {object} doc - Mutated datasource
+ * @returns {boolean} True if something was deleted from the tree
+ */
+function finalizeTestPayloadShape(doc) {
+  let changed = false;
+  const tp = doc.testPayload;
+  if (!tp || typeof tp !== 'object') {
+    return false;
+  }
+  if (Array.isArray(tp.scenarios) && tp.scenarios.length === 0) {
+    delete tp.scenarios;
+    changed = true;
+  }
+  if (Object.keys(tp).length === 0) {
+    delete doc.testPayload;
+    changed = true;
+  }
+  return changed;
+}
+
+/**
+ * Remove `exposed.profiles` when it is an empty object after profile deletion.
+ *
+ * @param {object} doc - Mutated datasource
+ * @returns {boolean} True if `exposed.profiles` was removed
+ */
+function finalizeEmptyExposedProfiles(doc) {
+  if (!doc.exposed || typeof doc.exposed !== 'object') {
+    return false;
+  }
+  const prof = doc.exposed.profiles;
+  if (!prof || typeof prof !== 'object' || Object.keys(prof).length > 0) {
+    return false;
+  }
+  delete doc.exposed.profiles;
+  return true;
+}
+
+/**
+ * Mutate doc after capability slices removed: scenarios, empty containers, summary lines.
+ *
+ * @param {object} doc - Cloned datasource (mutated)
+ * @param {object} originalDoc - Original parsed JSON (for testPayload diff only)
+ * @param {string} logicalName
+ * @param {{ openapiKey?: string, cipKey?: string }} removedKeys - Actual openapi/CIP object keys removed
+ * @param {string[]} updatedSections - Human-readable sections changed
+ * @returns {void}
+ */
+function applyCapabilityRemoveSideEffects(
+  doc,
+  originalDoc,
+  logicalName,
+  removedKeys,
+  updatedSections
+) {
+  const openapiKey = removedKeys?.openapiKey;
+  const cipKey = removedKeys?.cipKey;
+  const testPayloadBeforeJson = JSON.stringify(originalDoc.testPayload);
+  pruneTestPayloadScenarios(doc, logicalName, openapiKey, cipKey);
+  finalizeTestPayloadShape(doc);
+
+  const ooPath = openapiKey ?? logicalName;
+  const cipPath = cipKey ?? logicalName;
+  updatedSections.push(
+    'removed: capabilities / openapi.operations.' +
+      ooPath +
+      ' / execution.cip.operations.' +
+      cipPath,
+    'exposed.profiles / testPayload.scenarios (see JSON Patch paths)'
+  );
+
+  if (finalizeEmptyExposedProfiles(doc)) {
+    updatedSections.push('exposed.profiles (removed empty object)');
+  }
+
+  if (testPayloadBeforeJson !== JSON.stringify(doc.testPayload)) {
+    updatedSections.push('testPayload');
+  }
+}
+
+/**
+ * Apply capability removal on a deep clone of the document.
+ *
+ * @param {object} originalDoc - Parsed datasource JSON
+ * @param {object} opts - Options
+ * @param {string} opts.capability - Capability key to remove
+ * @param {boolean} [opts.force=false] - If true and capability absent, return unchanged doc
+ * @returns {{
+ *   doc: object,
+ *   removed: boolean,
+ *   patchOperations: object[],
+ *   updatedSections: string[]
+ * }}
+ */
+function applyCapabilityRemove(originalDoc, opts) {
+  const doc = deepClone(originalDoc);
+  const name = opts.capability;
+  const updatedSections = [];
+
+  if (!capabilityExists(doc, name)) {
+    if (!opts.force) {
+      throw new Error(
+        `Capability "${name}" not found in capabilities[], openapi.operations, or execution.cip.operations. ` +
+          'Use --force to succeed when the capability is already absent.'
+      );
+    }
+    return {
+      doc,
+      removed: false,
+      patchOperations: [],
+      updatedSections: ['capability already absent (--force)']
+    };
+  }
+
+  const logicalName = resolveLogicalNameForRemove(doc, name);
+  const openapiKey = findMatchingOpsKeys(originalDoc.openapi?.operations, logicalName)[0];
+  const cipKey = findMatchingOpsKeys(originalDoc.execution?.cip?.operations, logicalName)[0];
+  const profileKey = resolveProfileKeyForLogical(originalDoc, logicalName);
+
+  const patchOperations = buildRemovePatchOperations(
+    originalDoc,
+    logicalName,
+    openapiKey,
+    cipKey,
+    profileKey
+  );
+
+  removeCapability(doc, logicalName);
+  applyCapabilityRemoveSideEffects(doc, originalDoc, logicalName, { openapiKey, cipKey }, updatedSections);
+
+  return {
+    doc,
+    removed: true,
+    patchOperations,
+    updatedSections
+  };
+}
+
+module.exports = {
+  applyCapabilityRemove,
+  buildRemovePatchOperations,
+  pruneTestPayloadScenarios,
+  finalizeTestPayloadShape,
+  finalizeEmptyExposedProfiles
+};

package/lib/datasource/capability/run-capability-copy.js

@@ -0,0 +1,152 @@
+/**
+ * File-backed capability copy with validation, backup, and atomic write.
+ *
+ * @fileoverview Run datasource capability copy CLI operation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('node:fs');
+const path = require('path');
+const { writeBackup } = require('../../utils/integration-file-backup');
+const {
+  resolveValidateInputPath,
+  validateDatasourceParsed
+} = require('../validate');
+const { normalizeCapabilityKey } = require('./capability-key');
+const { applyCapabilityCreate } = require('./create-operations');
+
+/**
+ * Resolve an existing JSON file path using real disk (`node:fs`). Other suites often
+ * `jest.mock('fs')`; `require('fs')` would see the mock and break existsSync/read here.
+ * @param {string} identifier - Trimmed path or datasource key
+ * @returns {string} Absolute path to file
+ */
+function resolveCapabilityCopyInputPath(identifier) {
+  const trimmed = String(identifier || '').trim();
+  if (!trimmed) {
+    throw new Error('File path is required and must be a string');
+  }
+  const candidates = [...new Set([trimmed, path.resolve(trimmed)])];
+  for (const p of candidates) {
+    try {
+      if (!fs.existsSync(p)) continue;
+      try {
+        const st = fs.statSync(p);
+        if (st && typeof st.isFile === 'function' && st.isFile()) {
+          return path.resolve(p);
+        }
+      } catch {
+        return path.resolve(p);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return resolveValidateInputPath(trimmed);
+}
+
+/**
+ * @param {string} filePath
+ * @param {object} obj
+ * @returns {void}
+ */
+function atomicWriteJson(filePath, obj) {
+  const dir = path.dirname(filePath);
+  const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
+  const payload = `${JSON.stringify(obj, null, 2)}\n`;
+  fs.writeFileSync(tmp, payload, 'utf8');
+  fs.renameSync(tmp, filePath);
+}
+
+/**
+ * @typedef {object} RunCapabilityCopyOpts
+ * @property {string} fileOrKey - Path or datasource key
+ * @property {string} from
+ * @property {string} as - Target capability key
+ * @property {boolean} [dryRun=false]
+ * @property {boolean} [overwrite=false]
+ * @property {boolean} [noBackup=false]
+ * @property {boolean} [basicExposure=false] - Programmatic only: minimal exposed.profiles from metadataSchema (CLI always passes false)
+ * @property {boolean} [includeTestPayload=false] - Also clone testPayload.scenarios rows matching the source operation (`--test` on CLI)
+ * @property {string} [openApiOperationId] - Create without --from: match openapi.operations[].operationId
+ * @property {string} [template] - Create without --from: template name under capability/templates/
+ */
+
+/**
+ * Execute capability copy on disk (or dry-run).
+ *
+ * @param {RunCapabilityCopyOpts} opts
+ * @returns {Promise<{
+ *   dryRun: boolean,
+ *   resolvedPath: string,
+ *   resolvedAs: string,
+ *   patchOperations: object[],
+ *   updatedSections: string[],
+ *   backupPath: string|null,
+ *   validation: object
+ * }>}
+ */
+async function runCapabilityCopy(opts) {
+  const resolvedPath = resolveCapabilityCopyInputPath(opts.fileOrKey.trim());
+  const raw = fs.readFileSync(resolvedPath, 'utf8');
+  const parsed = JSON.parse(raw);
+
+  const to = normalizeCapabilityKey(opts.as, 'Target (--as)');
+  const fromRaw = opts.from !== undefined && opts.from !== null ? String(opts.from).trim() : '';
+  const from = fromRaw ? normalizeCapabilityKey(fromRaw, 'Source (--from)') : '';
+  const oidRaw =
+    opts.openApiOperationId !== undefined && opts.openApiOperationId !== null
+      ? String(opts.openApiOperationId).trim()
+      : '';
+  const tplRaw =
+    opts.template !== undefined && opts.template !== null ? String(opts.template).trim() : '';
+
+  const result = applyCapabilityCreate(parsed, {
+    from: from || undefined,
+    to,
+    openApiOperationId: oidRaw || undefined,
+    template: tplRaw || undefined,
+    overwrite: Boolean(opts.overwrite),
+    basicExposure: Boolean(opts.basicExposure),
+    includeTestPayload: Boolean(opts.includeTestPayload)
+  });
+
+  const validation = validateDatasourceParsed(result.doc);
+  if (!validation.valid) {
+    const err = new Error(validation.errors.join('\n'));
+    err.validationErrors = validation.errors;
+    throw err;
+  }
+
+  if (opts.dryRun) {
+    return {
+      dryRun: true,
+      resolvedPath,
+      resolvedAs: result.resolvedAs,
+      patchOperations: result.patchOperations,
+      updatedSections: result.updatedSections,
+      backupPath: null,
+      validation
+    };
+  }
+
+  const backupPath = writeBackup(resolvedPath, Boolean(opts.noBackup));
+  atomicWriteJson(resolvedPath, result.doc);
+
+  return {
+    dryRun: false,
+    resolvedPath,
+    resolvedAs: result.resolvedAs,
+    patchOperations: result.patchOperations,
+    updatedSections: result.updatedSections,
+    backupPath,
+    validation
+  };
+}
+
+module.exports = {
+  runCapabilityCopy,
+  writeBackup,
+  atomicWriteJson
+};