@aifabrix/builder 2.45.0 → 2.45.5

package/lib/identity/identity-csv-parser.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Parse controller users.csv-style files for identity apply
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { readFileSync } = require('../internal/fs-real-sync');
+
+/**
+ * Parse one CSV line respecting double-quoted fields.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function parseCsvLine(line) {
+  const out = [];
+  let cur = '';
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i];
+    if (ch === '"') {
+      if (inQuotes && line[i + 1] === '"') {
+        cur += '"';
+        i += 1;
+      } else {
+        inQuotes = !inQuotes;
+      }
+    } else if (ch === ',' && !inQuotes) {
+      out.push(cur.trim());
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  out.push(cur.trim());
+  return out;
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} [filterPrefix]
+ * @returns {{ headers: string[], rows: Object[] }}
+ */
+function parseUsersCsvFile(filePath, filterPrefix = '') {
+  const raw = readFileSync(filePath, 'utf8');
+  const lines = raw.split(/\r?\n/).filter((l) => l.trim().length > 0);
+  if (lines.length < 2) {
+    throw new Error('CSV must include a header row and at least one data row');
+  }
+  const headers = parseCsvLine(lines[0]);
+  const prefix = String(filterPrefix || '').trim();
+  const rows = [];
+  for (let i = 1; i < lines.length; i += 1) {
+    const cells = parseCsvLine(lines[i]);
+    const row = {};
+    headers.forEach((h, idx) => {
+      row[h] = cells[idx] !== undefined ? cells[idx] : '';
+    });
+    const id = String(row.Id || row.id || '').trim();
+    if (prefix && id && !id.startsWith(prefix)) {
+      continue;
+    }
+    rows.push(row);
+  }
+  return { headers, rows };
+}
+
+/**
+ * Build unique entities from CSV rows (users.csv shape).
+ * @param {Object[]} rows
+ * @returns {{ groups: Map<string, { name: string, displayName: string }>, users: Map<string, Object>, memberships: { userKey: string, groupName: string }[] }}
+ */
+// eslint-disable-next-line complexity -- row shape varies; logic is linear per field
+function buildApplyPlanFromRows(rows) {
+  const groups = new Map();
+  const users = new Map();
+  const memberships = [];
+
+  for (const row of rows) {
+    const csvId = String(row.Id || row.id || '').trim();
+    const email = String(row.Email || row.email || '').trim();
+    if (!email) {
+      continue;
+    }
+    const userKey = csvId || email;
+    const groupName = String(row.GroupId || row.groupId || '').trim();
+    const groupDisplay = String(row.GroupName || row.groupName || groupName).trim();
+    if (groupName) {
+      if (!groups.has(groupName)) {
+        groups.set(groupName, { name: groupName, displayName: groupDisplay || groupName });
+      }
+      memberships.push({ userKey, groupName });
+    }
+    if (!users.has(userKey)) {
+      users.set(userKey, {
+        csvId,
+        email,
+        firstName: String(row.FirstName || row.firstName || '').trim() || undefined,
+        lastName: String(row.LastName || row.lastName || '').trim() || undefined,
+        displayName: String(row.DisplayName || row.displayName || '').trim() || undefined,
+        username: String(row.UserPrincipalName || row.userPrincipalName || row.username || '').trim() || undefined
+      });
+    }
+  }
+
+  return { groups, users, memberships };
+}
+
+module.exports = {
+  parseCsvLine,
+  parseUsersCsvFile,
+  buildApplyPlanFromRows
+};

package/lib/internal/fs-real-sync.js

@@ -93,6 +93,31 @@ function readdirSync(p, opts) {
   return delegate('readdirSync', opts !== undefined ? [p, opts] : [p]);
 }
 
+/**
+ * @param {string} prefix
+ * @returns {string}
+ */
+function mkdtempSync(prefix) {
+  return delegate('mkdtempSync', [prefix]);
+}
+
+/**
+ * @param {string} p
+ * @param {import('node:fs').RmOptions} [opts]
+ * @returns {void}
+ */
+function rmSync(p, opts) {
+  return delegate('rmSync', opts !== undefined ? [p, opts] : [p]);
+}
+
+/**
+ * @param {string} p
+ * @returns {void}
+ */
+function unlinkSync(p) {
+  return delegate('unlinkSync', [p]);
+}
+
 module.exports = {
   existsSync,
   readFileSync,
@@ -100,5 +125,8 @@ module.exports = {
   writeFileSync,
   mkdirSync,
   statSync,
-  readdirSync
+  readdirSync,
+  mkdtempSync,
+  rmSync,
+  unlinkSync
 };

package/lib/protection/auth-context.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Dataplane auth/url resolution for protection commands.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveEnvironment } = require('../core/config');
+const { getDeviceOnlyAuth, getDeploymentAuth } = require('../utils/token-manager');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.env]
+ * @returns {Promise<{ environment: string, controllerUrl: string, dataplaneUrl: string, authConfig: Object }>}
+ */
+async function resolveProtectionDataplaneContext(options = {}) {
+  const environment = options.env || (await resolveEnvironment());
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error('Controller URL is required. Run "aifabrix login" first.');
+  }
+
+  let authConfig;
+  try {
+    authConfig = await getDeviceOnlyAuth(controllerUrl);
+  } catch {
+    authConfig = await getDeploymentAuth(controllerUrl, environment, 'dataplane');
+  }
+
+  if (!authConfig?.token) {
+    throw new Error(
+      'Authentication required. Run "aifabrix login" and try again.'
+    );
+  }
+
+  const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+  return { environment, controllerUrl, dataplaneUrl, authConfig };
+}
+
+module.exports = {
+  resolveProtectionDataplaneContext
+};

package/lib/protection/convert-batch.js

@@ -0,0 +1,90 @@
+/**
+ * @fileoverview Convert all protection manifests in `.protection/` between JSON and YAML.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { existsSync, unlinkSync } = require('../internal/fs-real-sync');
+const { getProtectionRoot } = require('./paths');
+const { listProtectionManifestPaths } = require('./resolve');
+const { promptConfirm, targetFileName, convertOneFile } = require('../commands/convert');
+
+/**
+ * @param {string} root
+ * @param {string} format
+ * @returns {string[]}
+ */
+function listFilesNeedingConvert(root, format) {
+  const targetExt = format === 'json' ? '.json' : '.yaml';
+  return listProtectionManifestPaths(root).filter((p) => {
+    return path.extname(p).toLowerCase() !== targetExt;
+  });
+}
+
+/**
+ * @param {string[]} toConvert
+ * @param {string} format
+ * @param {boolean} force
+ * @returns {Promise<void>}
+ */
+async function confirmProtectionConvert(toConvert, format, force) {
+  if (force) {
+    return;
+  }
+  const lines = toConvert.map((p) => `  • ${path.basename(p)} → ${targetFileName(p, format)}`);
+  const confirmed = await promptConfirm(
+    `Convert all protection manifests to ${format}?\n${lines.join('\n')}\nAre you sure? (y/N) `
+  );
+  if (!confirmed) {
+    throw new Error('Convert cancelled.');
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string[]} toConvert
+ * @param {string} format
+ * @returns {{ converted: string[], deleted: string[] }}
+ */
+function convertProtectionFiles(root, toConvert, format) {
+  const converted = [];
+  const deleted = [];
+  for (const sourcePath of toConvert) {
+    const targetPath = path.join(root, targetFileName(sourcePath, format));
+    convertOneFile(sourcePath, targetPath, format);
+    converted.push(targetPath);
+    if (path.normalize(sourcePath) !== path.normalize(targetPath)) {
+      unlinkSync(sourcePath);
+      deleted.push(sourcePath);
+    }
+  }
+  return { converted, deleted };
+}
+
+/**
+ * @param {string} format - `yaml` | `json`
+ * @param {Object} opts
+ * @returns {Promise<{ converted: string[], deleted: string[] }>}
+ */
+async function runConvertProtectionBatch(format, opts = {}) {
+  const root = opts.root || getProtectionRoot();
+  if (!existsSync(root)) {
+    throw new Error(`Protection folder not found: ${root}`);
+  }
+  const toConvert = listFilesNeedingConvert(root, format);
+  if (!toConvert.length) {
+    return { converted: [], deleted: [] };
+  }
+  await confirmProtectionConvert(toConvert, format, opts.force === true);
+  return convertProtectionFiles(root, toConvert, format);
+}
+
+module.exports = {
+  runConvertProtectionBatch,
+  listFilesNeedingConvert,
+  confirmProtectionConvert,
+  convertProtectionFiles
+};

package/lib/protection/load.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Load protection manifest YAML files (v1).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { existsSync, readFileSync } = require('../internal/fs-real-sync');
+const { yamlToJson } = require('../utils/config-format');
+
+/**
+ * @param {string} manifestPath - Absolute path to `.yaml` manifest
+ * @returns {Object} Parsed manifest object
+ */
+function loadProtectionManifest(manifestPath) {
+  const p = path.resolve(String(manifestPath || '').trim());
+  if (!p) {
+    throw new Error('Protection manifest path is required');
+  }
+  if (!existsSync(p)) {
+    throw new Error(`Protection manifest not found: ${p}`);
+  }
+  const ext = path.extname(p).toLowerCase();
+  if (ext !== '.yaml' && ext !== '.yml' && ext !== '.json') {
+    throw new Error(
+      `Protection manifest must be .yaml, .yml, or .json (got ${ext || '(none)'}).`
+    );
+  }
+  const content = readFileSync(p, 'utf8');
+  if (ext === '.json') {
+    const parsed = JSON.parse(content);
+    return parsed === undefined || parsed === null ? {} : parsed;
+  }
+  return yamlToJson(content);
+}
+
+module.exports = {
+  loadProtectionManifest
+};

package/lib/protection/paths.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Protection manifest directory under repo `integration/.protection/`.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getAppsMaterializationParent,
+  getCwdIntegrationRoot
+} = require('../utils/paths');
+const { nodeFs } = require('../internal/node-fs');
+
+/**
+ * Walk upward from cwd for the nearest directory containing `integration/`.
+ *
+ * @returns {string|null} Absolute path to `integration/` or null
+ */
+function findNearestIntegrationRootFromCwd() {
+  const disk = nodeFs();
+  let walk = path.resolve(process.cwd());
+  for (let i = 0; i < 64; i += 1) {
+    const integrationDir = path.join(walk, 'integration');
+    try {
+      if (disk.existsSync(integrationDir)) {
+        const st = disk.statSync(integrationDir);
+        if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+          return integrationDir;
+        }
+      }
+    } catch {
+      // ignore
+    }
+    const parent = path.dirname(walk);
+    if (parent === walk) {
+      break;
+    }
+    walk = parent;
+  }
+  return null;
+}
+
+/**
+ * Canonical repo-local protection root: `integration/.protection/`.
+ *
+ * @returns {string}
+ */
+function getRepoProtectionRoot() {
+  const cwdInt = getCwdIntegrationRoot();
+  if (cwdInt) {
+    return path.join(cwdInt, '.protection');
+  }
+  const materializationParent = path.resolve(getAppsMaterializationParent());
+  const nearest = findNearestIntegrationRootFromCwd();
+  if (nearest) {
+    const resolvedNearest = path.resolve(nearest);
+    if (
+      resolvedNearest === materializationParent ||
+      resolvedNearest.startsWith(`${materializationParent}${path.sep}`)
+    ) {
+      return path.join(resolvedNearest, '.protection');
+    }
+  }
+  return path.join(materializationParent, 'integration', '.protection');
+}
+
+/**
+ * @returns {string}
+ */
+function getLegacyProtectionRoot() {
+  return path.join(getAppsMaterializationParent(), '.protection');
+}
+
+/**
+ * @param {string} root
+ * @returns {boolean}
+ */
+function protectionRootHasManifestFiles(root) {
+  if (!root || !fs.existsSync(root)) {
+    return false;
+  }
+  try {
+    return fs.readdirSync(root).some((name) => /\.(yaml|yml|json)$/i.test(name));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {string} Absolute path to protection manifests directory
+ */
+function getProtectionRoot() {
+  const explicit = process.env.AIFABRIX_PROTECTION_ROOT;
+  if (explicit && typeof explicit === 'string' && explicit.trim()) {
+    return path.resolve(explicit.trim());
+  }
+
+  const legacyFlag =
+    process.env.AIFABRIX_PROTECTION_LEGACY === '1' ||
+    String(process.env.AIFABRIX_PROTECTION_LEGACY || '').toLowerCase() === 'true';
+
+  const repoRoot = getRepoProtectionRoot();
+  const legacyRoot = getLegacyProtectionRoot();
+
+  if (legacyFlag) {
+    return legacyRoot;
+  }
+
+  const repoHas = protectionRootHasManifestFiles(repoRoot);
+  const legacyHas = protectionRootHasManifestFiles(legacyRoot);
+
+  if (!repoHas && legacyHas && legacyRoot !== repoRoot) {
+    return legacyRoot;
+  }
+
+  return repoRoot;
+}
+
+/**
+ * Human-readable folder label for batch protection TTY output.
+ *
+ * @returns {{ root: string, label: string, usingLegacy: boolean, migrationHint: string|null }}
+ */
+function describeProtectionRoot() {
+  const root = getProtectionRoot();
+  const legacyRoot = getLegacyProtectionRoot();
+  const repoRoot = getRepoProtectionRoot();
+  const usingLegacy = path.resolve(root) === path.resolve(legacyRoot);
+  const legacyHas = protectionRootHasManifestFiles(legacyRoot);
+  const repoHas = protectionRootHasManifestFiles(repoRoot);
+
+  let label = 'integration/.protection';
+  if (usingLegacy) {
+    label = 'work/.protection (legacy)';
+  } else if (process.env.AIFABRIX_PROTECTION_ROOT) {
+    label = 'custom';
+  }
+
+  let migrationHint = null;
+  if (usingLegacy && legacyHas) {
+    migrationHint = `Move manifests to ${repoRoot} (git-friendly integration/.protection/).`;
+  } else if (!usingLegacy && legacyHas && !repoHas) {
+    migrationHint = `Legacy manifests remain under ${legacyRoot}; migrate to ${repoRoot}.`;
+  }
+
+  return { root, label, usingLegacy, migrationHint };
+}
+
+module.exports = {
+  getProtectionRoot,
+  describeProtectionRoot,
+  getRepoProtectionRoot,
+  getLegacyProtectionRoot,
+  findNearestIntegrationRootFromCwd
+};

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
+};