@aifabrix/builder 2.50.0 → 2.51.0

package/lib/commands/evidence-kind.js

@@ -0,0 +1,428 @@
+/**
+ * Evidence kind catalog commands (Controller).
+ *
+ * Commands:
+ * - aifabrix evidence-kind create|import|export|get|list
+ *
+ * Distinct from `aifabrix evidence` (Evidence Fabrix v2 rows).
+ *
+ * @fileoverview Evidence kind catalog CLI commands
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { normalizeControllerUrl, resolveEnvironment } = require('../core/config');
+const { getOrRefreshDeviceToken } = require('../utils/token-manager');
+const {
+  readEvidenceKindCreateFile,
+  readEvidenceKindCatalogFile,
+  writeEvidenceKindCatalogFile,
+  mapEvidenceKindFileToApiPayload,
+  mapEvidenceKindApiToFileRow
+} = require('../resolvers/evidence-kind-file');
+const {
+  formatBlockingError,
+  formatSuccessLine,
+  infoLine,
+  headerKeyValue
+} = require('../utils/cli-layout-chalk');
+const {
+  listEvidenceKinds,
+  getEvidenceKind,
+  createEvidenceKindIdempotent
+} = require('../api/evidence-kinds.api');
+
+const EVIDENCE_KIND_KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+const EVIDENCE_KIND_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence-kind create --key obligation --display-name "Obligation" --domain governance --purpose "Track commitments"
+  $ aifabrix evidence-kind get obligation
+  $ aifabrix evidence-kind list --search risk
+
+Per-command help:  aifabrix evidence-kind <command> --help
+`;
+
+const EVIDENCE_KIND_IMPORT_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence-kind import --file ./baseline-evidence-kinds.json
+`;
+
+const EVIDENCE_KIND_EXPORT_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence-kind export --file ./evidence-kinds-export.json
+`;
+
+const EVIDENCE_KIND_CREATE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence-kind create --key obligation --display-name "Obligation" --domain governance --purpose "Track commitments"
+  $ aifabrix evidence-kind create --key risk --display-name "Risk" --domain governance --purpose "..." --default-severity high
+  $ aifabrix evidence-kind create --file ./obligation.json
+`;
+
+const EVIDENCE_KIND_GET_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence-kind get obligation
+  $ aifabrix evidence-kind get clx1234567890abcdef
+`;
+
+const EVIDENCE_KIND_LIST_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence-kind list
+  $ aifabrix evidence-kind list --page 1 --page-size 50
+  $ aifabrix evidence-kind list --search risk
+`;
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function requireEvidenceKindKey(raw) {
+  const key = String(raw || '').trim();
+  if (!key) {
+    throw new Error('Evidence kind key is required (--key <key> or --file <path>).');
+  }
+  if (!EVIDENCE_KIND_KEY_PATTERN.test(key)) {
+    throw new Error(
+      'Evidence kind key must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.'
+    );
+  }
+  return key;
+}
+
+/**
+ * @param {Object} _options
+ * @returns {Promise<{ controllerUrl: string, authConfig: Object }>}
+ */
+async function resolveControllerAndAuth(_options) {
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error('Controller URL is required. Run "aifabrix login" first.');
+  }
+  const normalized = normalizeControllerUrl(controllerUrl);
+  const deviceToken = await getOrRefreshDeviceToken(normalized);
+  if (!deviceToken || !deviceToken.token) {
+    throw new Error(
+      `Not authenticated for controller: ${controllerUrl}. ` +
+        'Run "aifabrix login" and try again.'
+    );
+  }
+  return {
+    controllerUrl: deviceToken.controller || normalized,
+    authConfig: { type: 'bearer', token: deviceToken.token }
+  };
+}
+
+async function resolveHeaderContext() {
+  const env = await resolveEnvironment();
+  const controllerUrl = await resolveControllerUrl();
+  const normalized = normalizeControllerUrl(controllerUrl);
+  return { environment: env || 'dev', controllerUrl: normalized };
+}
+
+/**
+ * @param {Object} response
+ * @returns {any}
+ */
+function unwrapControllerData(response) {
+  return response?.data?.data ?? response?.data ?? response;
+}
+
+/**
+ * Build create payload from flags and optional --file (maps domain → domainKey).
+ * @param {Object} options
+ * @returns {Object}
+ */
+function buildCreatePayload(options) {
+  let base = {};
+  if (options.file) {
+    base = readEvidenceKindCreateFile(options.file);
+  }
+  const merged = { ...base };
+  if (options.key) merged.key = options.key;
+  if (options.displayName) merged.displayName = options.displayName;
+  if (options.description !== undefined) merged.description = options.description;
+  if (options.purpose !== undefined) merged.purpose = options.purpose;
+  if (options.expectedUse !== undefined) merged.expectedUse = options.expectedUse;
+  if (options.defaultSeverity) merged.defaultSeverity = options.defaultSeverity;
+  if (options.domain) {
+    merged.domain = options.domain;
+    delete merged.domainKey;
+  }
+  if (options.file && !options.domain && base.domainKey) {
+    return { ...base, key: requireEvidenceKindKey(merged.key || base.key) };
+  }
+  const payload = mapEvidenceKindFileToApiPayload(
+    {
+      ...merged,
+      domain: merged.domain || merged.domainKey
+    },
+    0
+  );
+  payload.key = requireEvidenceKindKey(payload.key);
+  return payload;
+}
+
+/**
+ * @param {Object[]} rows
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @returns {Promise<{ created: number, existed: number, total: number }>}
+ */
+async function importEvidenceKindRows(rows, controllerUrl, authConfig) {
+  let created = 0;
+  let existed = 0;
+  for (const payload of rows) {
+    payload.key = requireEvidenceKindKey(payload.key);
+    const out = await createEvidenceKindIdempotent(controllerUrl, authConfig, payload);
+    if (out.created) {
+      created += 1;
+      continue;
+    }
+    existed += 1;
+  }
+  return { created, existed, total: rows.length };
+}
+
+/**
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @returns {Promise<Object[]>}
+ */
+async function fetchAllEvidenceKinds(controllerUrl, authConfig) {
+  const all = [];
+  let page = 1;
+  const pageSize = 100;
+  for (;;) {
+    const res = await listEvidenceKinds(controllerUrl, authConfig, { page, pageSize });
+    const payload = unwrapControllerData(res);
+    const items = payload?.data ?? payload ?? [];
+    if (!Array.isArray(items) || items.length === 0) {
+      break;
+    }
+    all.push(...items);
+    if (items.length < pageSize) {
+      break;
+    }
+    page += 1;
+  }
+  return all;
+}
+
+function setupEvidenceKindImportCommand(cmd) {
+  cmd
+    .command('import')
+    .description('Import evidence kinds from baseline JSON (idempotent)')
+    .addHelpText('after', EVIDENCE_KIND_IMPORT_HELP_AFTER)
+    .requiredOption('--file <path>', 'Baseline catalog (evidenceKinds[]) or JSON array')
+    .action(async(options) => {
+      try {
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const rows = readEvidenceKindCatalogFile(options.file);
+        const summary = await importEvidenceKindRows(rows, controllerUrl, authConfig);
+        logger.log(
+          formatSuccessLine(
+            `Evidence kinds imported: ${summary.total} total ` +
+              `(${summary.created} created, ${summary.existed} already existed)`
+          )
+        );
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+function setupEvidenceKindExportCommand(cmd) {
+  cmd
+    .command('export')
+    .description('Export evidence kinds to baseline-shaped JSON')
+    .addHelpText('after', EVIDENCE_KIND_EXPORT_HELP_AFTER)
+    .requiredOption('--file <path>', 'Output path for baseline catalog JSON')
+    .action(async(options) => {
+      try {
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const records = await fetchAllEvidenceKinds(controllerUrl, authConfig);
+        const rows = records.map(mapEvidenceKindApiToFileRow);
+        writeEvidenceKindCatalogFile(options.file, rows);
+        logger.log(
+          formatSuccessLine(`Evidence kinds exported: ${rows.length} written to ${options.file}`)
+        );
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+function setupEvidenceKindCreateCommand(cmd) {
+  cmd
+    .command('create')
+    .description('Create evidence kind (idempotent; success if it already exists)')
+    .addHelpText('after', EVIDENCE_KIND_CREATE_HELP_AFTER)
+    .option('--file <path>', 'Read evidence kind create payload from JSON file')
+    .option('--key <key>', 'Catalog key (lowercase letters, digits, underscores)')
+    .option('--display-name <name>', 'Display name')
+    .option('--domain <domain>', 'Enterprise domain key (e.g. governance, sales)')
+    .option('--purpose <text>', 'Evidence kind purpose (required)')
+    .option('--expected-use <text>', 'Expected use guidance')
+    .option('--default-severity <level>', 'low | medium | high | critical')
+    .option('--description <text>', 'Description')
+    .action(async(options) => {
+      try {
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const payload = buildCreatePayload(options);
+        const out = await createEvidenceKindIdempotent(controllerUrl, authConfig, payload);
+        const row = unwrapControllerData(out.response);
+        const domain = row.domainKey || payload.domainKey || '—';
+        if (out.created) {
+          logger.log(formatSuccessLine(`Evidence kind created: ${row.key} (domain: ${domain})`));
+          return;
+        }
+        logger.log(formatSuccessLine(`Evidence kind exists: ${row.key} (domain: ${domain})`));
+        logger.log(infoLine('No changes were needed.'));
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+function setupEvidenceKindGetCommand(cmd) {
+  cmd
+    .command('get <evidenceKindIdOrKey>')
+    .description('Get evidence kind by id or key')
+    .addHelpText('after', EVIDENCE_KIND_GET_HELP_AFTER)
+    .action(async(evidenceKindIdOrKey, options) => {
+      try {
+        const { environment, controllerUrl: headerControllerUrl } = await resolveHeaderContext();
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const res = await getEvidenceKind(controllerUrl, authConfig, String(evidenceKindIdOrKey).trim());
+        const row = unwrapControllerData(res);
+        logger.log(
+          chalk.bold(
+            `\n📎  Evidence kind in ${environment} environment (${headerControllerUrl}):\n`
+          )
+        );
+        logger.log(headerKeyValue('Key:', row.key || '—'));
+        logger.log(headerKeyValue('Display:', row.displayName || '—'));
+        logger.log(headerKeyValue('Domain:', row.domainKey || '—'));
+        logger.log(headerKeyValue('Purpose:', row.purpose || '—'));
+        logger.log(headerKeyValue('Severity:', row.defaultSeverity || '—'));
+        logger.log(headerKeyValue('Active:', row.isActive === false ? 'false' : 'true'));
+        if (row.expectedUse) logger.log(headerKeyValue('Expected use:', row.expectedUse));
+        if (row.description) logger.log(headerKeyValue('Description:', row.description));
+        logger.log('');
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+const EVIDENCE_KIND_LIST_COLUMNS = { key: 24, display: 24, domain: 14, severity: 10, active: 8 };
+
+function logEvidenceKindListHeader(columns) {
+  const keyCol = 'Key'.padEnd(columns.key);
+  const displayCol = 'Display'.padEnd(columns.display);
+  const domainCol = 'Domain'.padEnd(columns.domain);
+  const severityCol = 'Severity'.padEnd(columns.severity);
+  const activeCol = 'Active'.padEnd(columns.active);
+  logger.log(chalk.gray(`${keyCol}${displayCol}${domainCol}${severityCol}${activeCol}`));
+  logger.log(
+    chalk.gray(
+      '-'.repeat(
+        columns.key + columns.display + columns.domain + columns.severity + columns.active
+      )
+    )
+  );
+}
+
+function logEvidenceKindListRows(items, columns) {
+  items.forEach((d) => {
+    const key = (d?.key ?? '—').toString().padEnd(columns.key);
+    const displayName = (d?.displayName ?? '—').toString().padEnd(columns.display);
+    const domain = (d?.domainKey ?? '—').toString().padEnd(columns.domain);
+    const severity = (d?.defaultSeverity ?? '—').toString().padEnd(columns.severity);
+    const active = (d?.isActive === false ? 'false' : 'true').padEnd(columns.active);
+    logger.log(`${key}${displayName}${domain}${severity}${active}`);
+  });
+}
+
+function displayEvidenceKindList(items, environment, controllerUrl) {
+  logger.log(
+    chalk.bold(`\n📎  Evidence kinds in ${environment} environment (${controllerUrl}):\n`)
+  );
+  if (!Array.isArray(items) || items.length === 0) {
+    logger.log(chalk.gray('  No evidence kinds found.\n'));
+    return;
+  }
+  logEvidenceKindListHeader(EVIDENCE_KIND_LIST_COLUMNS);
+  logEvidenceKindListRows(items, EVIDENCE_KIND_LIST_COLUMNS);
+  logger.log('');
+}
+
+function setupEvidenceKindListCommand(cmd) {
+  cmd
+    .command('list')
+    .description('List evidence kinds')
+    .addHelpText('after', EVIDENCE_KIND_LIST_HELP_AFTER)
+    .option('--page <n>', 'Page', (v) => parseInt(v, 10))
+    .option('--page-size <n>', 'Page size', (v) => parseInt(v, 10))
+    .option('--search <text>', 'Search by key/displayName/description')
+    .option('--domain-key <domain>', 'Filter by domain key')
+    .action(async(options) => {
+      try {
+        const { environment, controllerUrl: headerControllerUrl } = await resolveHeaderContext();
+        const { controllerUrl, authConfig } = await resolveControllerAndAuth(options);
+        const res = await listEvidenceKinds(controllerUrl, authConfig, {
+          page: options.page,
+          pageSize: options.pageSize,
+          search: options.search,
+          domainKey: options.domainKey
+        });
+        const payload = unwrapControllerData(res);
+        const items = payload?.data ?? payload ?? [];
+        displayEvidenceKindList(items, environment, headerControllerUrl);
+      } catch (e) {
+        logger.error(formatBlockingError(e.message));
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupEvidenceKindCommands(program) {
+  const cmd = program
+    .command('evidence-kind')
+    .description('Manage the Controller Evidence Kind Catalog')
+    .addHelpText('after', EVIDENCE_KIND_HELP_AFTER);
+  setupEvidenceKindCreateCommand(cmd);
+  setupEvidenceKindImportCommand(cmd);
+  setupEvidenceKindExportCommand(cmd);
+  setupEvidenceKindGetCommand(cmd);
+  setupEvidenceKindListCommand(cmd);
+}
+
+module.exports = {
+  setupEvidenceKindCommands,
+  requireEvidenceKindKey,
+  buildCreatePayload,
+  unwrapControllerData,
+  importEvidenceKindRows,
+  mapEvidenceKindFileToApiPayload,
+  mapEvidenceKindApiToFileRow
+};

package/lib/commands/governance-command-action.js

@@ -14,6 +14,7 @@ const { displayVerifyGovernanceTTY } = require('../lifecycle/report-display');
 const { exitCodeFromVerdict } = require('../lifecycle/exit-codes');
 const { buildJsonEnvelope } = require('../lifecycle/json-envelope');
 const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 
 /**
  * Commander repeatable-option collector. Splits comma-separated values so both
@@ -31,11 +32,12 @@ function collectString(value, previous) {
 }
 
 function normalizeGovernanceOptions(options, cmd) {
-  const parent = cmd && cmd.parent ? cmd.parent.opts() : {};
+  const parentCmd = cmd && cmd.parent ? cmd.parent : null;
+  const parent = parentCmd ? parentCmd.opts() : {};
   return {
     env: options.env || parent.env || 'dev',
     verbose: options.verbose === true || parent.verbose === true,
-    noPublish: options.noPublish === true || parent.noPublish === true,
+    noPublish: cliOptsSkipPublish(options, cmd) || cliOptsSkipPublish(parent, parentCmd),
     force: options.force === true || parent.force === true,
     json: options.json === true || parent.json === true,
     pack: options.pack,

package/lib/commands/repair-openapi-export.js

@@ -30,7 +30,7 @@ function documentKeyToLocalOpenApiPath(appPath, systemKey, documentKey) {
 }
 
 /** @type {Set<string>} */
-const PROGRAMMATIC_ORCHESTRATION_SYSTEM_KEYS = new Set(['aifabrix-builder-api']);
+const PROGRAMMATIC_ORCHESTRATION_SYSTEM_KEYS = new Set(['builder-api']);
 
 /**
  * @param {string} systemKey

package/lib/commands/repair-openapi-sync.js

@@ -97,7 +97,7 @@ function extractOpenApiFileListItems(res) {
   const data = res && res.data;
   if (data && Array.isArray(data.data)) return data.data;
   if (data && Array.isArray(data.items)) return data.items;
-  if (res && Array.isArray(res.items)) return res.items;
+  if (Array.isArray(res.items)) return res.items;
   return [];
 }
 
@@ -140,13 +140,15 @@ async function syncOpenApiFilesForMcp(opts) {
     authConfig: opts.authConfig
   });
   const existingKeys = await getExistingOpenApiKeys(dataplaneUrl, systemKey, authConfig);
-  const uploadedKeys = new Set(existingKeys);
+  const uploadedThisRun = new Set();
   let uploaded = 0;
   let skipped = 0;
+  const forceUpload = opts.force === true;
 
   for (const fileName of datasourceFiles || []) {
     const documentKey = readDatasourceDocumentKey(appPath, fileName);
-    if (!documentKey || uploadedKeys.has(documentKey)) continue;
+    if (!documentKey || uploadedThisRun.has(documentKey)) continue;
+    if (!forceUpload && existingKeys.has(documentKey)) continue;
 
     const localPath = documentKeyToLocalOpenApiPath(appPath, systemKey, documentKey);
     if (!(await fileExistsAsync(localPath))) {
@@ -155,7 +157,7 @@ async function syncOpenApiFilesForMcp(opts) {
     }
 
     await uploadOneOpenApiFile(dataplaneUrl, authConfig, systemKey, localPath, documentKey);
-    uploadedKeys.add(documentKey);
+    uploadedThisRun.add(documentKey);
     uploaded += 1;
   }
 
@@ -177,7 +179,11 @@ async function maybeSyncOpenApiFilesForMcp(opts) {
   const r = await syncOpenApiFilesForMcp(opts);
   const lines = [];
   if (r.uploaded > 0) {
-    lines.push(`Uploaded ${r.uploaded} OpenAPI file(s) for MCP (keyed by openapi.documentKey)`);
+    lines.push(
+      opts.force
+        ? `Uploaded ${r.uploaded} OpenAPI file(s) for MCP (force replace by openapi.documentKey)`
+        : `Uploaded ${r.uploaded} OpenAPI file(s) for MCP (keyed by openapi.documentKey)`
+    );
   }
   if (r.skipped > 0) {
     lines.push(
@@ -215,7 +221,9 @@ async function maybeRunOpenApiSyncForMcp({
       dryRun,
       appPath,
       systemKey,
-      datasourceFiles
+      datasourceFiles,
+      // --api re-exports local OpenAPI; always replace SpecFile rows that already exist.
+      force: true
     });
     openapiLines.forEach((l) => changes.push(l));
     return exportLines.length > 0 || openapiLines.length > 0;