@aifabrix/builder 2.45.0 → 2.46.0

package/lib/protection/preflight-datasource-ready.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Preflight: datasource must exist on dataplane before protection upload.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getDatasource } = require('../api/datasources-core.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} datasourceKey
+ * @returns {Promise<void>}
+ */
+async function assertDatasourceExistsOnDataplane(dataplaneUrl, authConfig, datasourceKey) {
+  const key = String(datasourceKey || '').trim();
+  if (!key) {
+    throw new Error('spec.datasourceKey is required');
+  }
+  const res = await getDatasource(dataplaneUrl, key, authConfig);
+  const row = unwrapApiData(res);
+  if (!row || (res && res.success === false)) {
+    throw new Error(
+      `Datasource "${key}" is not deployed on the dataplane. Run aifabrix deploy <app> first.`
+    );
+  }
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} manifest
+ * @returns {Promise<void>}
+ */
+async function preflightDatasourceReady(dataplaneUrl, authConfig, manifest) {
+  const ds = String(manifest?.spec?.datasourceKey || '').trim();
+  await assertDatasourceExistsOnDataplane(dataplaneUrl, authConfig, ds);
+}
+
+module.exports = {
+  assertDatasourceExistsOnDataplane,
+  preflightDatasourceReady
+};

package/lib/protection/protection-create-probe-lines.js

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview TTY line builders for protection create probes (keeps probe async functions small).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const {
+  sectionTitle,
+  headerKeyValue,
+  metadata,
+  formatProgress,
+  formatSuccessLine
+} = require('../utils/cli-test-layout-chalk');
+
+const SEP = chalk.gray('────────────────────────────────────────');
+
+/**
+ * @param {string} key
+ * @returns {string[]}
+ */
+function startDatasourceProbeLines(key) {
+  return [sectionTitle('Datasource (dataplane)'), SEP, formatProgress(`Fetching datasource "${key}"…`)];
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} row
+ * @param {string} key
+ * @param {string} dataplaneUrl
+ */
+function appendDatasourceCoreFields(lines, row, key, dataplaneUrl) {
+  lines.push(formatSuccessLine(`Datasource "${key}" found`));
+  lines.push(metadata(`Dataplane: ${dataplaneUrl}`));
+  lines.push(headerKeyValue('Key:', row.key ?? key));
+  lines.push(headerKeyValue('Display name:', row.displayName ?? '—'));
+  lines.push(headerKeyValue('System key:', row.systemKey ?? '—'));
+  const ver = row.version;
+  lines.push(headerKeyValue('Version:', ver !== undefined && ver !== null ? String(ver) : '—'));
+  lines.push(headerKeyValue('Enabled:', String(row.enabled !== false)));
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} row
+ */
+function appendDatasourceOptionalTypes(lines, row) {
+  if (row.entityType) {
+    lines.push(headerKeyValue('Entity type:', String(row.entityType)));
+  }
+  if (row.resourceType) {
+    lines.push(headerKeyValue('Resource type:', String(row.resourceType)));
+  }
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} row
+ */
+function appendDatasourceVerboseBlock(lines, row) {
+  const pick = ['id', 'key', 'displayName', 'systemKey', 'version', 'enabled', 'entityType', 'resourceType'];
+  const extra = {};
+  for (const p of pick) {
+    if (row[p] !== undefined) {
+      extra[p] = row[p];
+    }
+  }
+  lines.push('');
+  lines.push(chalk.gray('Verbose (subset):'));
+  lines.push(chalk.gray(JSON.stringify(extra, null, 2)));
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} row
+ * @param {string} key
+ * @param {string} dataplaneUrl
+ * @param {Object} opts
+ */
+function appendDatasourceSuccessDetail(lines, row, key, dataplaneUrl, opts) {
+  appendDatasourceCoreFields(lines, row, key, dataplaneUrl);
+  appendDatasourceOptionalTypes(lines, row);
+  if (opts.verbose && row) {
+    appendDatasourceVerboseBlock(lines, row);
+  }
+  lines.push('');
+}
+
+/**
+ * @param {string} key
+ * @returns {string[]}
+ */
+function startDimensionProbeLines(key) {
+  return [
+    sectionTitle('Dimension (Controller catalog)'),
+    SEP,
+    formatProgress(`Fetching dimension "${key}"…`)
+  ];
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} row
+ * @param {string} controllerUrl
+ * @param {Object} opts
+ */
+function appendDimensionSuccessDetail(lines, row, controllerUrl, opts) {
+  lines.push(formatSuccessLine(`Dimension "${row.key}" found`));
+  lines.push(metadata(`Controller: ${controllerUrl}`));
+  lines.push(headerKeyValue('Key:', row.key));
+  lines.push(headerKeyValue('Display:', row.displayName ?? '—'));
+  lines.push(headerKeyValue('Data type:', row.dataType ?? '—'));
+  lines.push(headerKeyValue('Value type:', row.valueType ?? 'static'));
+  lines.push(headerKeyValue('Required:', String(row.isRequired === true)));
+  if (Array.isArray(row.dimensionValues) && row.dimensionValues.length > 0) {
+    lines.push(
+      headerKeyValue('Catalog values:', `${row.dimensionValues.length} (static/baseline)`)
+    );
+  } else if (row.valueType === 'dynamic' || row.valueType === 'both') {
+    lines.push(headerKeyValue('Catalog values:', '— (dynamic / projection)'));
+  }
+  if (opts.verbose && Array.isArray(row.dimensionValues) && row.dimensionValues.length) {
+    lines.push('');
+    lines.push(chalk.gray('Sample values (first 5):'));
+    row.dimensionValues.slice(0, 5).forEach((v) => {
+      const val = v && v.value !== undefined && v.value !== null ? String(v.value) : '—';
+      const dn = v?.displayName ? ` (${v.displayName})` : '';
+      lines.push(chalk.gray(`  ${val}${dn}`));
+    });
+  }
+  lines.push('');
+}
+
+module.exports = {
+  SEP,
+  startDatasourceProbeLines,
+  appendDatasourceSuccessDetail,
+  startDimensionProbeLines,
+  appendDimensionSuccessDetail
+};

package/lib/protection/protection-create-probes.js

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Online probes for `protection create` (dataplane datasource + Controller dimension).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getDatasource } = require('../api/datasources-core.api');
+const { getDimension } = require('../api/dimensions.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+const {
+  startDatasourceProbeLines,
+  appendDatasourceSuccessDetail,
+  startDimensionProbeLines,
+  appendDimensionSuccessDetail
+} = require('./protection-create-probe-lines');
+
+/**
+ * @param {*} response
+ * @returns {*}
+ */
+function unwrapControllerDimension(response) {
+  const d = response?.data?.data ?? response?.data ?? response;
+  return d;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {string} msg
+ * @returns {never}
+ */
+function throwProbe(lines, msg) {
+  const err = new Error(msg);
+  err.probeLines = lines;
+  throw err;
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} datasourceKey
+ * @param {Object} opts
+ * @returns {Promise<Object>}
+ */
+async function probeDatasourceForProtectionCreate(dataplaneUrl, authConfig, datasourceKey, opts = {}) {
+  const key = String(datasourceKey || '').trim();
+  const lines = startDatasourceProbeLines(key);
+  const res = await getDatasource(dataplaneUrl, key, authConfig);
+  if (res && res.success === false) {
+    const msg = res.formattedError || res.error || `Datasource "${key}" request failed`;
+    throwProbe(lines, typeof msg === 'string' ? msg : 'Datasource probe failed');
+  }
+  const row = unwrapApiData(res);
+  if (!row) {
+    throwProbe(
+      lines,
+      `Datasource "${key}" not found or not readable on the dataplane. Deploy the integration first.`
+    );
+  }
+  appendDatasourceSuccessDetail(lines, row, key, dataplaneUrl, opts);
+  return { row, lines };
+}
+
+/**
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} dimensionKey
+ * @param {Object} opts
+ * @returns {Promise<Object>}
+ */
+async function probeDimensionForProtectionCreate(controllerUrl, authConfig, dimensionKey, opts = {}) {
+  const key = String(dimensionKey || '').trim();
+  const lines = startDimensionProbeLines(key);
+  const res = await getDimension(controllerUrl, authConfig, key, { includeValues: opts.verbose === true });
+  if (res && res.success === false) {
+    const msg = res.formattedError || res.error || `Dimension "${key}" request failed`;
+    throwProbe(lines, typeof msg === 'string' ? msg : 'Dimension probe failed');
+  }
+  const row = unwrapControllerDimension(res);
+  if (!row || !row.key) {
+    throwProbe(
+      lines,
+      `Dimension "${key}" not found in the Controller catalog. Create it with: aifabrix dimension create …`
+    );
+  }
+  appendDimensionSuccessDetail(lines, row, controllerUrl, opts);
+  return { row, lines };
+}
+
+module.exports = {
+  probeDatasourceForProtectionCreate,
+  probeDimensionForProtectionCreate,
+  unwrapControllerDimension
+};

package/lib/protection/protection-create-scaffold.js

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview Build protection manifest objects for `protection create`.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { requireProtectionPreset } = require('./protection-preset-registry');
+
+const PROTECTION_KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+const DIMENSION_KEY_RE = /^[a-zA-Z][a-zA-Z0-9-_]*$/;
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function requireDatasourceKey(raw) {
+  const k = String(raw || '').trim();
+  if (!k) {
+    throw new Error('Datasource key is required');
+  }
+  if (!PROTECTION_KEY_RE.test(k)) {
+    throw new Error(
+      `Datasource key must match ${PROTECTION_KEY_RE}: got "${k}"`
+    );
+  }
+  return k;
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function requireDimensionKey(raw) {
+  const k = String(raw || '').trim();
+  if (!k) {
+    throw new Error('--dimension-key is required for protection create');
+  }
+  if (!DIMENSION_KEY_RE.test(k)) {
+    throw new Error(
+      'Dimension key must start with a letter and contain letters, numbers, hyphens, underscores only.'
+    );
+  }
+  return k;
+}
+
+/**
+ * @param {string} raw
+ * @param {string} fallback
+ * @returns {string}
+ */
+function protectionMetadataKey(raw, fallback) {
+  const k = String(raw || '').trim();
+  if (k) {
+    if (!PROTECTION_KEY_RE.test(k)) {
+      throw new Error(`--protection-key must match ${PROTECTION_KEY_RE}: got "${k}"`);
+    }
+    return k;
+  }
+  return fallback;
+}
+
+/**
+ * @param {Object} vars
+ * @param {string} vars.datasourceKey
+ * @param {string} vars.dimensionKey
+ * @param {string} [vars.protectionKey]
+ * @param {string} [vars.displayName]
+ * @param {string} [vars.ruleKey]
+ * @param {Object} vars.principal
+ * @param {string} vars.valueExpression
+ * @param {Object} [vars.when]
+ * @returns {Object}
+ */
+function buildProtectionManifest(vars) {
+  const datasourceKey = requireDatasourceKey(vars.datasourceKey);
+  const dimensionKey = requireDimensionKey(vars.dimensionKey);
+  const presetPart = vars.type ? `-${vars.type}` : '';
+  const protectionKey = protectionMetadataKey(
+    vars.protectionKey,
+    `${datasourceKey}-${dimensionKey}${presetPart}-access`
+  );
+  const ruleKey = String(vars.ruleKey || '').trim() || `${dimensionKey}${presetPart || '-access'}`;
+  const rule = {
+    key: ruleKey,
+    principal: vars.principal,
+    grants: [{ dimensionKey, valueExpression: vars.valueExpression }]
+  };
+  if (vars.when) {
+    rule.when = JSON.parse(JSON.stringify(vars.when));
+  }
+  return {
+    apiVersion: 'dataplane.aifabrix.ai/v1',
+    kind: 'Protection',
+    metadata: {
+      key: protectionKey,
+      displayName: String(vars.displayName || '').trim() || `${datasourceKey} — ${dimensionKey}`
+    },
+    spec: {
+      enabled: vars.enabled !== false,
+      datasourceKey,
+      mode: 'replaceForSource',
+      rules: [rule]
+    }
+  };
+}
+
+/**
+ * @param {Object} datasource
+ * @param {string} field
+ * @returns {boolean}
+ */
+function hasMetadataField(datasource, field) {
+  const props = datasource?.metadataSchema?.properties;
+  if (!props || typeof props !== 'object' || Array.isArray(props)) {
+    return true;
+  }
+  return Object.prototype.hasOwnProperty.call(props, field);
+}
+
+/**
+ * @param {Object} datasource
+ * @param {string} name
+ * @returns {Object|null}
+ */
+function findForeignKey(datasource, name) {
+  const fks = Array.isArray(datasource?.foreignKeys) ? datasource.foreignKeys : [];
+  return fks.find((fk) => fk && fk.name === name) || null;
+}
+
+/**
+ * @param {Object} datasource
+ * @param {string} field
+ */
+function assertMetadataField(datasource, field) {
+  if (!hasMetadataField(datasource, field)) {
+    throw new Error(`Preset field not found in datasource metadataSchema.properties: ${field}`);
+  }
+}
+
+/**
+ * @param {Object} preset
+ * @param {Object} dimension
+ */
+function assertDimensionValueType(preset, dimension) {
+  const valueType = String(dimension?.valueType || '').trim();
+  if (preset.staticOnly && valueType === 'dynamic') {
+    throw new Error(`Protection type "${preset.type}" requires a static or both dimension.`);
+  }
+  if (preset.dynamicOnly && valueType === 'static') {
+    throw new Error(`Protection type "${preset.type}" requires a dynamic or both dimension.`);
+  }
+}
+
+/**
+ * @param {Object} vars
+ * @param {Object} preset
+ * @returns {{ principal: Object, valueExpression: string, when: Object|undefined }}
+ */
+function resolveStandardPresetSpec(vars, preset) {
+  const field = String(vars.field || preset.valueField || preset.dimensionKey).trim();
+  assertMetadataField(vars.datasource, field);
+  const principal = vars.principalExpression
+    ? { type: 'group', expression: String(vars.principalExpression).trim() }
+    : principalFromPreset(vars, preset);
+  const valueExpression =
+    String(vars.valueExpression || '').trim() || preset.valueTemplate || `{{metadata.${field}}}`;
+  return { principal, valueExpression, when: preset.when };
+}
+
+/**
+ * @param {Object} vars
+ * @param {Object} preset
+ * @returns {Object}
+ */
+function principalFromPreset(vars, preset) {
+  if (preset.type === 'static-region') {
+    const displayField = hasMetadataField(vars.datasource, 'regionDisplayName') ? 'regionDisplayName' : 'region';
+    return { type: 'group', expression: `{{metadata.${displayField}}} Users` };
+  }
+  if (preset.principalType === 'user') {
+    assertMetadataField(vars.datasource, String(preset.principalField).replace(/^metadata\./, ''));
+    return { type: 'user', field: preset.principalField };
+  }
+  return { type: 'group', expression: preset.principalTemplate };
+}
+
+/**
+ * @param {Object} vars
+ * @param {Object} preset
+ * @returns {{ principal: Object, valueExpression: string }}
+ */
+function resolveCountrySalesSpec(vars, preset) {
+  const dimensionKey = vars.dimensionKey;
+  const fkName = String(vars.fkName || dimensionKey).trim();
+  const explicitField = String(vars.field || '').trim();
+  const fk = explicitField ? null : findForeignKey(vars.datasource, fkName);
+  if (vars.fkName && !fk) {
+    throw new Error(`Preset FK not found in datasource foreignKeys[].name: ${fkName}`);
+  }
+  if (fk) {
+    return {
+      principal: { type: 'group', expression: `Sales {{fk.${fkName}.metadata.iso3}} Users` },
+      valueExpression: String(vars.valueExpression || '').trim() || `{{fk.${fkName}.metadata.iso2}}`
+    };
+  }
+  const field = explicitField || preset.dimensionKey;
+  assertMetadataField(vars.datasource, field);
+  return {
+    principal: { type: 'group', expression: `Sales {{metadata.${field}}} Users` },
+    valueExpression: String(vars.valueExpression || '').trim() || `{{metadata.${field}}}`
+  };
+}
+
+/**
+ * @param {Object} vars
+ * @returns {Object}
+ */
+function buildPresetProtectionManifest(vars) {
+  const preset = requireProtectionPreset(vars.type);
+  if (!preset) {
+    return buildDynamicFkProtectionManifest(vars);
+  }
+  const dimensionKey = requireDimensionKey(vars.dimensionKey || preset.dimensionKey);
+  assertDimensionValueType(preset, vars.dimension);
+  const resolved = preset.type === 'country-sales'
+    ? resolveCountrySalesSpec({ ...vars, dimensionKey }, preset)
+    : resolveStandardPresetSpec({ ...vars, dimensionKey }, preset);
+  return buildProtectionManifest({
+    ...vars,
+    type: preset.type,
+    dimensionKey,
+    principal: resolved.principal,
+    valueExpression: resolved.valueExpression,
+    when: resolved.when
+  });
+}
+
+/**
+ * Build v1 "country-from-FK" style manifest (dynamic dimension from one-hop FK metadata).
+ *
+ * @param {Object} vars
+ * @param {string} vars.datasourceKey
+ * @param {string} vars.dimensionKey
+ * @param {string} [vars.fkName] - defaults to dimensionKey
+ * @param {string} [vars.protectionKey]
+ * @param {string} [vars.displayName]
+ * @param {string} [vars.ruleKey]
+ * @param {string} [vars.principalExpression]
+ * @param {string} [vars.valueExpression]
+ * @returns {Object}
+ */
+function buildDynamicFkProtectionManifest(vars) {
+  const datasourceKey = requireDatasourceKey(vars.datasourceKey);
+  const dimensionKey = requireDimensionKey(vars.dimensionKey);
+  const fkName = String(vars.fkName || dimensionKey).trim() || dimensionKey;
+  const principalExpression =
+    String(vars.principalExpression || '').trim() ||
+    `Sales {{fk.${fkName}.metadata.iso3}} Users`;
+  const valueExpression =
+    String(vars.valueExpression || '').trim() ||
+    `{{fk.${fkName}.metadata.iso2}}`;
+  return buildProtectionManifest({
+    ...vars,
+    datasourceKey,
+    dimensionKey,
+    ruleKey: vars.ruleKey || `${dimensionKey}-from-fk-users`,
+    displayName: vars.displayName || `${datasourceKey} — ${dimensionKey} (FK projection)`,
+    principal: { type: 'group', expression: principalExpression },
+    valueExpression
+  });
+}
+
+module.exports = {
+  buildPresetProtectionManifest,
+  buildDynamicFkProtectionManifest,
+  buildProtectionManifest,
+  requireDatasourceKey,
+  requireDimensionKey
+};