@aifabrix/builder 2.45.0 → 2.46.0

package/lib/protection/protection-preset-registry.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Deterministic preset registry for `aifabrix protection create --type`.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const ProtectionPresetRegistry = Object.freeze({
+  'country-sales': Object.freeze({
+    type: 'country-sales',
+    dimensionKey: 'country',
+    principalTemplate: 'Sales {{value}} Users',
+    valueTemplate: '{{value}}'
+  }),
+  'department-manager': Object.freeze({
+    type: 'department-manager',
+    dimensionKey: 'department',
+    principalType: 'user',
+    principalField: 'metadata.managerEmail',
+    valueField: 'department',
+    valueTemplate: '{{metadata.department}}',
+    requiresField: 'department',
+    when: Object.freeze({ groups: Object.freeze({ requireAny: Object.freeze(['Manager']) }) })
+  }),
+  'customer-team': Object.freeze({
+    type: 'customer-team',
+    dimensionKey: 'customer',
+    principalTemplate: 'Customer {{metadata.customer}} Team',
+    valueField: 'customer',
+    valueTemplate: '{{metadata.customer}}',
+    requiresField: 'customer'
+  }),
+  'project-team': Object.freeze({
+    type: 'project-team',
+    dimensionKey: 'project',
+    principalTemplate: 'Project {{metadata.project}} Team',
+    valueField: 'project',
+    valueTemplate: '{{metadata.project}}',
+    requiresField: 'project'
+  }),
+  'static-region': Object.freeze({
+    type: 'static-region',
+    dimensionKey: 'region',
+    principalTemplate: '{{metadata.regionDisplayName}} Users',
+    valueField: 'region',
+    valueTemplate: '{{metadata.region}}',
+    requiresField: 'region',
+    staticOnly: true
+  }),
+  'owner-direct': Object.freeze({
+    type: 'owner-direct',
+    dimensionKey: 'owner',
+    principalType: 'user',
+    principalField: 'metadata.ownerEmail',
+    valueField: 'owner',
+    valueTemplate: '{{metadata.owner}}',
+    requiresField: 'owner'
+  })
+});
+
+/**
+ * @returns {string[]}
+ */
+function listProtectionPresetTypes() {
+  return Object.keys(ProtectionPresetRegistry);
+}
+
+/**
+ * @param {string|undefined} type
+ * @returns {Object|null}
+ */
+function getProtectionPreset(type) {
+  const key = String(type || '').trim();
+  return key ? ProtectionPresetRegistry[key] || null : null;
+}
+
+/**
+ * @param {string|undefined} type
+ * @returns {Object|null}
+ */
+function requireProtectionPreset(type) {
+  const preset = getProtectionPreset(type);
+  if (preset || !String(type || '').trim()) {
+    return preset;
+  }
+  throw new Error(
+    `Unknown protection type "${type}". Supported types: ${listProtectionPresetTypes().join(', ')}`
+  );
+}
+
+module.exports = {
+  ProtectionPresetRegistry,
+  getProtectionPreset,
+  listProtectionPresetTypes,
+  requireProtectionPreset
+};

package/lib/protection/report-exit.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Exit codes for protection validate reports.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} report
+ * @returns {Object[]}
+ */
+function reportTaskRows(report) {
+  if (!report || typeof report !== 'object') {
+    return [];
+  }
+  if (Array.isArray(report.results)) {
+    return report.results;
+  }
+  if (Array.isArray(report.tasks)) {
+    return report.tasks;
+  }
+  return [];
+}
+
+/**
+ * @param {Object} report
+ * @param {Object} [opts]
+ * @param {boolean} [opts.warningsAsErrors]
+ * @returns {number} 0 ok, 1 fail/warn-as-error, 3 invalid input
+ */
+function exitCodeFromProtectionReport(report, opts = {}) {
+  if (!report || typeof report !== 'object') {
+    return 3;
+  }
+  const summary = report.summary || {};
+  const failCount = Number(summary.fail || 0);
+  const warnCount = Number(summary.warn || 0);
+  if (failCount > 0) {
+    return 1;
+  }
+  if (opts.warningsAsErrors === true && warnCount > 0) {
+    return 1;
+  }
+  const rows = reportTaskRows(report);
+  const hasFail = rows.some((r) => String(r?.status || '').toUpperCase() === 'FAIL');
+  if (hasFail) {
+    return 1;
+  }
+  if (opts.warningsAsErrors === true) {
+    const hasWarn = rows.some((r) => String(r?.status || '').toUpperCase() === 'WARN');
+    if (hasWarn) {
+      return 1;
+    }
+  }
+  return 0;
+}
+
+module.exports = {
+  reportTaskRows,
+  exitCodeFromProtectionReport
+};

package/lib/protection/resolve.js

@@ -0,0 +1,202 @@
+/**
+ * @fileoverview Resolve protection manifests by datasource key under `integration/.protection/`.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getProtectionRoot } = require('./paths');
+const { loadProtectionManifest } = require('./load');
+
+const PROTECTION_FILENAME_RE = /^([a-z0-9][a-z0-9-]*)-protection-([a-z0-9][a-z0-9-]*)$/i;
+
+/**
+ * @param {string} root
+ * @param {string} candidate
+ * @returns {boolean}
+ */
+function isPathInsideRoot(root, candidate) {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(candidate);
+  return resolved === resolvedRoot || resolved.startsWith(`${resolvedRoot}${path.sep}`);
+}
+
+/**
+ * @param {string} stem
+ * @returns {string|null}
+ */
+function datasourceKeyFromProtectionFilename(stem) {
+  const m = PROTECTION_FILENAME_RE.exec(stem);
+  if (!m) {
+    return null;
+  }
+  return `${m[1]}-${m[2]}`;
+}
+
+/**
+ * @param {string} root
+ * @returns {string[]}
+ */
+function listProtectionManifestPaths(root) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  return fs
+    .readdirSync(root)
+    .filter((name) => /\.(yaml|yml|json)$/i.test(name))
+    .map((name) => path.join(root, name))
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * @param {string} root
+ * @throws {Error}
+ */
+function assertNoDuplicateDatasourceKeys(root) {
+  const seen = new Map();
+  for (const filePath of listProtectionManifestPaths(root)) {
+    let manifest;
+    try {
+      manifest = loadProtectionManifest(filePath);
+    } catch {
+      continue;
+    }
+    const ds = String(manifest?.spec?.datasourceKey || '').trim();
+    if (!ds) {
+      continue;
+    }
+    if (seen.has(ds)) {
+      throw new Error(
+        `Duplicate spec.datasourceKey "${ds}" in .protection/ (${seen.get(ds)} and ${filePath})`
+      );
+    }
+    seen.set(ds, filePath);
+  }
+}
+
+/**
+ * @param {Object} manifest
+ * @param {string} key
+ * @param {string} location
+ */
+function assertManifestDatasourceKey(manifest, key, location) {
+  const specKey = String(manifest?.spec?.datasourceKey || '').trim();
+  if (specKey && specKey !== key) {
+    throw new Error(`spec.datasourceKey "${specKey}" does not match CLI argument "${key}"${location}`);
+  }
+}
+
+/**
+ * @param {string} key
+ * @param {string} manifestPath
+ * @param {Object} manifest
+ */
+function protectionManifestResult(key, manifestPath, manifest) {
+  assertManifestDatasourceKey(manifest, key, ` in ${manifestPath}`);
+  return { datasourceKey: key, manifestPath, manifest };
+}
+
+/**
+ * @param {string} key
+ * @param {string} root
+ * @returns {string[]}
+ */
+function collectProtectionManifestMatches(key, root) {
+  const matches = [];
+  for (const filePath of listProtectionManifestPaths(root)) {
+    const stem = path.basename(filePath, path.extname(filePath));
+    if (stem === key || datasourceKeyFromProtectionFilename(stem) === key) {
+      matches.push(filePath);
+      continue;
+    }
+    try {
+      const manifest = loadProtectionManifest(filePath);
+      if (String(manifest?.spec?.datasourceKey || '').trim() === key) {
+        matches.push(filePath);
+      }
+    } catch {
+      /* skip unreadable */
+    }
+  }
+  return matches;
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {string} [explicitPath]
+ * @returns {{ datasourceKey: string, manifestPath: string, manifest: Object }}
+ */
+function resolveProtectionManifest(datasourceKey, explicitPath) {
+  const key = String(datasourceKey || '').trim();
+  if (!key) throw new Error('Datasource key is required');
+
+  const root = getProtectionRoot();
+  assertNoDuplicateDatasourceKeys(root);
+
+  if (explicitPath) {
+    const manifestPath = path.resolve(explicitPath);
+    if (!isPathInsideRoot(root, manifestPath)) {
+      throw new Error(`Protection path must be under ${root}`);
+    }
+    return protectionManifestResult(key, manifestPath, loadProtectionManifest(manifestPath));
+  }
+
+  for (const ext of ['.yaml', '.yml', '.json']) {
+    const preferred = path.join(root, `${key}${ext}`);
+    if (fs.existsSync(preferred)) {
+      return protectionManifestResult(key, preferred, loadProtectionManifest(preferred));
+    }
+  }
+
+  const matches = collectProtectionManifestMatches(key, root);
+  if (matches.length === 0) {
+    throw new Error(
+      `No protection manifest for datasource "${key}" under ${root}. Expected ${key}.yaml or ${key}.json`
+    );
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous protection manifest for "${key}": ${matches.map((p) => path.basename(p)).join(', ')}`
+    );
+  }
+
+  const manifestPath = matches[0];
+  return protectionManifestResult(key, manifestPath, loadProtectionManifest(manifestPath));
+}
+
+/**
+ * @param {string} arg - CLI positional (datasource key or file path)
+ * @returns {{ datasourceKey: string, manifestPath: string, manifest: Object }}
+ */
+function resolveProtectionArgument(arg) {
+  const raw = String(arg || '').trim();
+  if (!raw) {
+    throw new Error('Datasource key is required');
+  }
+  const root = getProtectionRoot();
+  const asPath = path.resolve(raw);
+  if (fs.existsSync(asPath) && fs.statSync(asPath).isFile()) {
+    if (!isPathInsideRoot(root, asPath)) {
+      throw new Error(`Protection file must be under ${root}`);
+    }
+    const manifest = loadProtectionManifest(asPath);
+    const ds = String(manifest?.spec?.datasourceKey || '').trim();
+    if (!ds) {
+      throw new Error('Manifest spec.datasourceKey is required');
+    }
+    return resolveProtectionManifest(ds, asPath);
+  }
+  return resolveProtectionManifest(raw);
+}
+
+module.exports = {
+  resolveProtectionManifest,
+  resolveProtectionArgument,
+  listProtectionManifestPaths,
+  datasourceKeyFromProtectionFilename,
+  isPathInsideRoot,
+  assertNoDuplicateDatasourceKeys
+};

package/lib/protection/run-commands-validate.js

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Dataplane validation path for protection validate command.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const { validateProtectionManifestLocal } = require('./validate-local');
+const { resolveProtectionDataplaneContext } = require('./auth-context');
+const { validateProtection, simulateProtection } = require('../api/protection.api');
+const { exitCodeFromProtectionReport } = require('./report-exit');
+const {
+  printProtectionValidateReport,
+  formatProgress,
+  formatSuccessLine,
+  formatBlockingError,
+  metadata,
+  headerKeyValue,
+  sectionTitle,
+  SEP
+} = require('./protection-display');
+
+/**
+ * @param {Object} logger
+ * @param {Object} resolved
+ * @param {Object} ctx
+ */
+function printProtectionTargetHeader(logger, resolved, ctx) {
+  logger.log(sectionTitle('Target'));
+  logger.log(SEP);
+  logger.log(headerKeyValue('Environment:', ctx.environment));
+  logger.log(headerKeyValue('Dataplane:', ctx.dataplaneUrl));
+  logger.log('');
+  logger.log(metadata(`Protection: work — ${resolved.manifestPath}`));
+  logger.log(headerKeyValue('Datasource:', resolved.datasourceKey));
+  logger.log('');
+}
+
+/**
+ * @param {Object} manifest
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {number}
+ */
+function runLocalSchemaGate(manifest, opts, logger) {
+  const local = validateProtectionManifestLocal(manifest);
+  if (!local.valid) {
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ valid: false, errors: local.errors }, null, 2));
+      return 1;
+    }
+    logger.error(formatBlockingError('Local schema check failed:'));
+    local.errors.forEach((e) => logger.error(chalk.gray(`  ${e}`)));
+    return 1;
+  }
+  if (opts.json) {
+    logger.log(formatProgress('Local schema valid'));
+  } else {
+    logger.log(formatProgress('Local schema check...'));
+    logger.log(formatSuccessLine('Local schema valid'));
+  }
+  return 0;
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Object} manifest
+ * @param {Object} opts
+ * @param {Object} logger
+ * @param {string} datasourceKey
+ * @param {string} manifestPath
+ * @returns {Promise<number>}
+ */
+async function runDataplaneProtectionValidate(ctx, manifest, opts, logger, datasourceKey, manifestPath) {
+  printProtectionTargetHeader(logger, { datasourceKey, manifestPath }, ctx);
+  logger.log(formatProgress('Dataplane validation...'));
+  const report = await validateProtection(ctx.dataplaneUrl, ctx.authConfig, manifest, {
+    strict: opts.warningsAsErrors === true
+  });
+  let simulationBlock = null;
+  if (opts.simulate && exitCodeFromProtectionReport(report, opts) === 0) {
+    const sim = await simulateProtection(ctx.dataplaneUrl, ctx.authConfig, manifest, {
+      strict: opts.warningsAsErrors === true
+    });
+    const meta = sim?.metadata || {};
+    simulationBlock = {
+      recordsSampled: meta.recordsSampled,
+      grantsProjected: meta.grantsProjected,
+      unresolvedPrincipals: meta.unresolvedPrincipals
+    };
+  }
+  printProtectionValidateReport(report, {
+    json: opts.json,
+    verbose: opts.verbose,
+    warningsAsErrors: opts.warningsAsErrors,
+    simulationBlock,
+    logger
+  });
+  return exitCodeFromProtectionReport(report, opts);
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} manifest
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {Promise<number>}
+ */
+async function runProtectionValidate(datasourceKey, manifest, opts, logger) {
+  const localCode = runLocalSchemaGate(manifest, opts, logger);
+  if (localCode !== 0) {
+    return localCode;
+  }
+  const ctx = await resolveProtectionDataplaneContext(opts);
+  return runDataplaneProtectionValidate(
+    ctx,
+    manifest,
+    opts,
+    logger,
+    datasourceKey,
+    opts.manifestPath
+  );
+}
+
+module.exports = {
+  printProtectionTargetHeader,
+  runProtectionValidate
+};

package/lib/protection/run-commands.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Single-manifest protection command implementations.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { resolveProtectionArgument } = require('./resolve');
+const { runProtectionValidate } = require('./run-commands-validate');
+const { resolveProtectionDataplaneContext } = require('./auth-context');
+const {
+  uploadProtection,
+  getProtection,
+  getProtectionStatus,
+  deleteProtection,
+  findProtectionKeyByDatasource
+} = require('../api/protection.api');
+const { preflightDatasourceReady } = require('./preflight-datasource-ready');
+const { syncDatasourceAfterProtectionUpload } = require('./sync-after-upload');
+const {
+  formatProtectionListTTY,
+  formatProtectionShowTTY,
+  formatProtectionDeleteSummaryTTY,
+  formatProgress,
+  formatSuccessLine,
+  formatWarningLine
+} = require('./protection-display');
+const { listProtectionManifests } = require('../api/protection.api');
+const { getProtectionRoot } = require('./paths');
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} manifest
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {Promise<number>}
+ */
+async function runProtectionUpload(datasourceKey, manifest, opts, logger) {
+  const code = await runProtectionValidate(datasourceKey, manifest, {
+    ...opts,
+    simulate: false,
+    json: false
+  }, logger);
+  if (code !== 0) {
+    return code;
+  }
+
+  const ctx = await resolveProtectionDataplaneContext(opts);
+  await preflightDatasourceReady(ctx.dataplaneUrl, ctx.authConfig, manifest);
+
+  if (opts.dryRun) {
+    logger.log(formatWarningLine('Dry run: would upload protection (no mutation).'));
+    logger.log(
+      chalk.gray(
+        `  key=${manifest?.metadata?.key || '—'} datasource=${datasourceKey} rules=${(manifest?.spec?.rules || []).length}`
+      )
+    );
+    return 0;
+  }
+
+  logger.log(formatProgress('Uploading protection manifest...'));
+  const uploaded = await uploadProtection(ctx.dataplaneUrl, ctx.authConfig, manifest);
+  logger.log(
+    formatSuccessLine(
+      `Protection for '${datasourceKey}' uploaded (deploymentId ${uploaded?.deploymentId || '—'}, revision ${uploaded?.revision ?? '—'})`
+    )
+  );
+
+  if (!opts.noSync) {
+    logger.log(formatProgress(`Syncing datasource ${datasourceKey}...`));
+    const sync = await syncDatasourceAfterProtectionUpload(
+      ctx.dataplaneUrl,
+      ctx.authConfig,
+      datasourceKey
+    );
+    if (sync.syncJobId) {
+      logger.log(formatSuccessLine(`Sync started (syncJobId: ${sync.syncJobId})`));
+    } else if (sync.warning) {
+      logger.log(formatWarningLine(`Sync warning: ${sync.warning}`));
+    }
+  } else {
+    logger.log(
+      chalk.gray(
+        'Sync skipped (--no-sync). Protection active on dataplane; projections update on next datasource sync.'
+      )
+    );
+  }
+  return 0;
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {Promise<string|null>}
+ */
+async function resolveProtectionKeyForDatasource(datasourceKey, ctx) {
+  try {
+    const resolved = resolveProtectionArgument(datasourceKey);
+    return String(resolved.manifest?.metadata?.key || '').trim() || null;
+  } catch {
+    return findProtectionKeyByDatasource(ctx.dataplaneUrl, ctx.authConfig, datasourceKey);
+  }
+}
+
+/**
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {Promise<number>}
+ */
+async function runProtectionList(opts, logger) {
+  const ctx = await resolveProtectionDataplaneContext(opts);
+  const params = {};
+  if (opts.page !== undefined && opts.page !== null && !Number.isNaN(Number(opts.page))) {
+    params.page = Number(opts.page);
+  }
+  if (
+    opts.pageSize !== undefined &&
+    opts.pageSize !== null &&
+    !Number.isNaN(Number(opts.pageSize))
+  ) {
+    params.pageSize = Number(opts.pageSize);
+  }
+  if (opts.filter && String(opts.filter).trim()) {
+    params.filter = String(opts.filter).trim();
+  }
+
+  const listed = await listProtectionManifests(ctx.dataplaneUrl, ctx.authConfig, params);
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(listed.raw ?? { data: listed.items, meta: listed.meta }, null, 2)}\n`
+    );
+    return 0;
+  }
+
+  logger.log(
+    formatProtectionListTTY(
+      {
+        items: listed.items,
+        meta: listed.meta,
+        environment: ctx.environment,
+        dataplaneUrl: ctx.dataplaneUrl
+      },
+      { verbose: opts.verbose === true }
+    )
+  );
+  return 0;
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {Promise<number>}
+ */
+async function runProtectionShow(datasourceKey, opts, logger) {
+  const ctx = await resolveProtectionDataplaneContext(opts);
+  const protectionKey = await resolveProtectionKeyForDatasource(datasourceKey, ctx);
+  if (!protectionKey) {
+    throw new Error(`No deployed protection found for datasource "${datasourceKey}"`);
+  }
+  const manifest = await getProtection(ctx.dataplaneUrl, ctx.authConfig, protectionKey);
+  const status = await getProtectionStatus(ctx.dataplaneUrl, ctx.authConfig, protectionKey);
+  const payload = { manifest, status, environment: ctx.environment, dataplaneUrl: ctx.dataplaneUrl };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, 2));
+    return 0;
+  }
+  logger.log(formatProtectionShowTTY(payload, { verbose: opts.verbose }));
+  return 0;
+}
+
+/**
+ * @param {string} datasourceKey
+ * @param {Object} opts
+ * @param {Object} logger
+ * @returns {Promise<number>}
+ */
+async function runProtectionDelete(datasourceKey, opts, logger) {
+  const ctx = await resolveProtectionDataplaneContext(opts);
+  const protectionKey = await resolveProtectionKeyForDatasource(datasourceKey, ctx);
+  if (!protectionKey) {
+    throw new Error(`No deployed protection found for datasource "${datasourceKey}"`);
+  }
+
+  if (!opts.yes) {
+    const { confirmed } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirmed',
+        message: `Delete protection for '${datasourceKey}' (${protectionKey})?`,
+        default: false
+      }
+    ]);
+    if (!confirmed) {
+      logger.log(chalk.gray('Delete cancelled.'));
+      return 0;
+    }
+  }
+
+  const res = await deleteProtection(ctx.dataplaneUrl, ctx.authConfig, protectionKey);
+  logger.log(formatProtectionDeleteSummaryTTY(res?.data || res, datasourceKey));
+  return 0;
+}
+
+module.exports = {
+  getProtectionRoot,
+  runProtectionValidate,
+  runProtectionUpload,
+  runProtectionList,
+  runProtectionShow,
+  runProtectionDelete
+};