@aifabrix/builder 2.49.2 → 2.51.0

package/lib/commands/enterprise-knowledge.js

@@ -0,0 +1,284 @@
+/**
+ * Enterprise Knowledge CLI commands (456.16).
+ *
+ * @fileoverview enterprise-knowledge generate-manifest
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  existsSync,
+  readFileSync,
+  mkdirSync,
+  writeFileSync
+} = require('../internal/fs-real-sync');
+const path = require('path');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveDataplaneAndAuth } = require('./upload');
+const { postGenerateManifest } = require('../api/enterprise-knowledge.api');
+const { getEnterpriseKnowledgePath } = require('../utils/enterprise-knowledge-paths');
+const { resolveAppWorkspace } = require('../utils/app-path-resolve');
+const {
+  formatBlockingError,
+  formatSuccessLine,
+  formatWarningLine,
+  infoLine,
+  headerKeyValue
+} = require('../utils/cli-layout-chalk');
+const { formatApiError } = require('../utils/api-error-handler');
+
+const DOMAIN_PATTERN = /^[a-z][a-z0-9-]*$/;
+const GENERATED_DIR = 'generated-service-contracts';
+const DEFAULT_PREVIEW_FILE = 'generate-manifest-preview.json';
+
+const ENTERPRISE_KNOWLEDGE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix enterprise-knowledge generate-manifest --domain sales
+  $ aifabrix enterprise-knowledge generate-manifest --domain sales --source-system hubspot-e2e
+  $ aifabrix enterprise-knowledge generate-manifest --domain sales --output ./preview.json
+
+Per-command help:  aifabrix enterprise-knowledge <command> --help
+`;
+
+const GENERATE_MANIFEST_HELP_AFTER = `
+
+Examples:
+  $ aifabrix enterprise-knowledge generate-manifest --domain sales
+  $ aifabrix enterprise-knowledge generate-manifest --domain sales --owner-system-key ek-sales
+  $ aifabrix enterprise-knowledge generate-manifest --domain sales --source-system vendor-crm --json
+
+Preview only — review output before upload (candidate) and deploy.
+
+`;
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function requireDomain(raw) {
+  const domain = String(raw || '').trim().toLowerCase();
+  if (!domain) {
+    throw new Error('--domain is required.');
+  }
+  if (!DOMAIN_PATTERN.test(domain)) {
+    throw new Error(
+      'domain must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.'
+    );
+  }
+  return domain;
+}
+
+/**
+ * @param {string} domain
+ * @param {string|undefined|null} raw
+ * @returns {string}
+ */
+function resolveOwnerSystemKey(domain, raw) {
+  const key = String(raw || '').trim() || `ek-${domain}`;
+  if (!/^[a-z0-9-_]+$/.test(key)) {
+    throw new Error('owner-system-key must contain only lowercase letters, numbers, hyphens, and underscores.');
+  }
+  return key;
+}
+
+/**
+ * @param {string} ownerSystemKey
+ * @returns {Object[]}
+ */
+function loadAnchorSubscriptions(ownerSystemKey) {
+  try {
+    const { appPath } = resolveAppWorkspace(ownerSystemKey, {
+      workspace: 'enterprise-knowledge'
+    });
+    const systemFile = path.join(appPath, `${ownerSystemKey}-system.json`);
+    if (!existsSync(systemFile)) {
+      return [];
+    }
+    const raw = JSON.parse(readFileSync(systemFile, 'utf8'));
+    return Array.isArray(raw.subscriptions) ? raw.subscriptions : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {Object} options
+ * @param {string} domain
+ * @param {string} ownerSystemKey
+ * @returns {import('../api/types/enterprise-knowledge.types').GenerateManifestRequest}
+ */
+function buildGenerateManifestRequest(options, domain, ownerSystemKey) {
+  if (options.file) {
+    const filePath = path.resolve(String(options.file));
+    if (!existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('Request file must be a JSON object.');
+    }
+    return {
+      domain: requireDomain(parsed.domain || domain),
+      ownerSystemKey: resolveOwnerSystemKey(domain, parsed.ownerSystemKey || ownerSystemKey),
+      displayName: parsed.displayName,
+      description: parsed.description,
+      subscriptions: Array.isArray(parsed.subscriptions) ? parsed.subscriptions : [],
+      sourceSystemKeys: Array.isArray(parsed.sourceSystemKeys) ? parsed.sourceSystemKeys : [],
+      version: parsed.version
+    };
+  }
+
+  const sourceKeys = [];
+  if (Array.isArray(options.sourceSystem)) {
+    sourceKeys.push(...options.sourceSystem.map((k) => String(k).trim()).filter(Boolean));
+  } else if (typeof options.sourceSystem === 'string' && options.sourceSystem.trim()) {
+    sourceKeys.push(options.sourceSystem.trim());
+  }
+
+  const subscriptions = loadAnchorSubscriptions(ownerSystemKey);
+  const title = domain.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+
+  return {
+    domain,
+    ownerSystemKey,
+    displayName: options.displayName || `Enterprise Knowledge — ${title}`,
+    description:
+      options.description ||
+      `Domain enterprise-knowledge preview for ${domain}. Human approval required before upload.`,
+    subscriptions,
+    sourceSystemKeys: sourceKeys,
+    version: options.version || '1.0.0'
+  };
+}
+
+/**
+ * @param {string} ownerSystemKey
+ * @param {string|undefined|null} outputOption
+ * @returns {string}
+ */
+function resolveOutputPath(ownerSystemKey, outputOption) {
+  if (outputOption) {
+    return path.resolve(String(outputOption));
+  }
+  const anchorDir = getEnterpriseKnowledgePath(ownerSystemKey);
+  return path.join(anchorDir, GENERATED_DIR, DEFAULT_PREVIEW_FILE);
+}
+
+/**
+ * @param {import('../api/types/enterprise-knowledge.types').GenerateManifestResponse} preview
+ * @returns {void}
+ */
+function logPreviewSummary(preview) {
+  headerKeyValue('Enterprise Knowledge manifest preview', preview.ownerSystemKey);
+  infoLine('Status', preview.previewOnly ? 'preview only (not published)' : 'unexpected');
+  infoLine('Version', preview.version || '1.0.0');
+  infoLine('Generated datasources', String((preview.externalDataSources || []).length));
+  const compilerCount = (preview.compilerFindings || []).length;
+  const trustCount = (preview.trustFindings || []).length;
+  if (compilerCount > 0) {
+    formatWarningLine(`${compilerCount} compiler finding(s) require review`);
+  }
+  if (trustCount > 0) {
+    formatWarningLine(`${trustCount} trust finding(s) require review`);
+  }
+  if (preview.message) {
+    logger.log(chalk.gray(preview.message));
+  }
+}
+
+/**
+ * @param {Object} options
+ * @returns {Promise<void>}
+ */
+async function runGenerateManifestCommand(options) {
+  const domain = requireDomain(options.domain);
+  const ownerSystemKey = resolveOwnerSystemKey(domain, options.ownerSystemKey);
+  const body = buildGenerateManifestRequest(options, domain, ownerSystemKey);
+
+  const { dataplaneUrl, authConfig } = await resolveDataplaneAndAuth(ownerSystemKey, {
+    silent: true
+  });
+  const controllerUrl = await resolveControllerUrl();
+
+  let preview;
+  try {
+    preview = await postGenerateManifest(dataplaneUrl, authConfig, body, { controllerUrl });
+  } catch (error) {
+    throw new Error(formatApiError(error, dataplaneUrl));
+  }
+
+  if (options.json) {
+    logger.log(JSON.stringify(preview, null, 2));
+    return;
+  }
+
+  const outputPath = resolveOutputPath(ownerSystemKey, options.output);
+  mkdirSync(path.dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(preview, null, 2)}\n`, 'utf8');
+
+  logPreviewSummary(preview);
+  formatSuccessLine(`Preview written to ${outputPath}`);
+  logger.log(chalk.gray('Review and edit before upload (candidate) and deploy.'));
+}
+
+/**
+ * @param {import('commander').Command} ek
+ * @returns {void}
+ */
+function setupGenerateManifestCommand(ek) {
+  ek.command('generate-manifest')
+    .description('Preview full Enterprise Knowledge manifest from published Connected Systems')
+    .addHelpText('after', GENERATE_MANIFEST_HELP_AFTER)
+    .requiredOption('--domain <domain>', 'Business domain slug (e.g. sales)')
+    .option('--owner-system-key <key>', 'Enterprise Knowledge anchor key (default ek-<domain>)')
+    .option('--source-system <key>', 'Published Connected System key (repeatable)', collectValues, [])
+    .option('--display-name <name>', 'Enterprise Knowledge display name override')
+    .option('--description <text>', 'Enterprise Knowledge description override')
+    .option('--version <semver>', 'Manifest version label', '1.0.0')
+    .option('--file <path>', 'Full request JSON (overrides built-in body)')
+    .option('--output <path>', 'Write preview JSON to this path')
+    .option('--json', 'Print preview JSON to stdout instead of writing a file')
+    .action(async(options) => {
+      try {
+        await runGenerateManifestCommand(options);
+      } catch (error) {
+        formatBlockingError(error.message || String(error));
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * @param {string} value
+ * @param {string[]} previous
+ * @returns {string[]}
+ */
+function collectValues(value, previous) {
+  return previous.concat([value]);
+}
+
+/**
+ * @param {import('commander').Command} program
+ * @returns {void}
+ */
+function setupEnterpriseKnowledgeCommands(program) {
+  const ek = program
+    .command('enterprise-knowledge')
+    .description('Enterprise Knowledge authoring helpers')
+    .addHelpText('after', ENTERPRISE_KNOWLEDGE_HELP_AFTER);
+  setupGenerateManifestCommand(ek);
+}
+
+module.exports = {
+  setupEnterpriseKnowledgeCommands,
+  runGenerateManifestCommand,
+  buildGenerateManifestRequest,
+  resolveOutputPath,
+  requireDomain,
+  resolveOwnerSystemKey
+};

package/lib/commands/evidence-cli-leaves.js

@@ -0,0 +1,250 @@
+/**
+ * @fileoverview Evidence Fabrix v2 CLI leaf command registration.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
+const {
+  exitCodeForEvidenceError,
+  runEvidenceList,
+  runEvidenceGet,
+  runEvidenceInsert,
+  runEvidenceUpdate,
+  runEvidenceDelete,
+  runEvidenceLoad,
+  runEvidenceExport,
+  DEFAULT_BULK_FILE
+} = require('../evidence/evidence-service');
+
+const SHARED_OPTS = [
+  ['-e, --env <environment>', 'Environment key'],
+  ['--json', 'Machine-readable JSON output']
+];
+
+const LIST_HELP = `
+
+Examples:
+  $ aifabrix evidence list
+  $ aifabrix evidence list --resource-type deal --generic
+  $ aifabrix evidence list --role-key sales-executive --status active --json
+`;
+
+const GET_HELP = `
+
+Examples:
+  $ aifabrix evidence get ev2_abc123
+  $ aifabrix evidence get ev2_abc123 --json
+`;
+
+const INSERT_HELP = `
+
+Examples:
+  $ aifabrix evidence insert --resource-type deal --title "High-value review" --when "Amount over threshold" --expected-behavior "Procurement review first"
+  $ aifabrix evidence insert --file ./row.json
+`;
+
+const UPDATE_HELP = `
+
+Examples:
+  $ aifabrix evidence update ev2_abc123 --title "Updated title"
+  $ aifabrix evidence update ev2_abc123 --file ./patch.json
+`;
+
+const DELETE_HELP = `
+
+Examples:
+  $ aifabrix evidence delete ev2_abc123 --yes
+  $ aifabrix evidence delete ev2_abc123
+
+Delete succeeds only when the row is not referenced by runtime execution.
+`;
+
+const LOAD_HELP = `
+
+Examples:
+  $ aifabrix evidence load --file ${DEFAULT_BULK_FILE}
+  $ aifabrix evidence load --dry-run
+`;
+
+const EXPORT_HELP = `
+
+Examples:
+  $ aifabrix evidence export --file ${DEFAULT_BULK_FILE}
+  $ aifabrix evidence export --resource-type deal --json
+`;
+
+/**
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ * @param {string} description
+ * @param {Function} action
+ * @param {Array<[string, string]>} extraOpts
+ * @param {string} helpAfter
+ */
+function addEvidenceLeaf(cmd, name, description, action, extraOpts = [], helpAfter = '') {
+  const leaf = cmd.command(name).description(description);
+  for (const [flags, desc] of [...SHARED_OPTS, ...extraOpts]) {
+    leaf.option(flags, desc);
+  }
+  if (helpAfter) {
+    leaf.addHelpText('after', helpAfter);
+  }
+  leaf.action(async(...args) => {
+    try {
+      const code = await action(...args);
+      if (code && code !== 0) {
+        process.exit(code);
+      }
+    } catch (err) {
+      logger.error(formatBlockingError(err.message || String(err)));
+      process.exit(exitCodeForEvidenceError(err));
+    }
+  });
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceList(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'list',
+    'List Evidence Fabrix v2 rows from the dataplane',
+    async(options) => runEvidenceList(options, logger),
+    [
+      ['--resource-type <resourceType>', 'Filter by resource type'],
+      ['--role-key <roleKey>', 'Filter by role-specific scope'],
+      ['--generic', 'Generic rows only (no roleKey)'],
+      ['--status <status>', 'Filter by active or disabled']
+    ],
+    LIST_HELP
+  );
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceGet(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'get <evidenceId>',
+    'Get one evidence row by id',
+    async(evidenceId, options) => runEvidenceGet(evidenceId, options, logger),
+    [],
+    GET_HELP
+  );
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceInsert(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'insert',
+    'Insert a new evidence row',
+    async(options) => runEvidenceInsert(options, logger),
+    [
+      ['--file <path>', 'Single evidence JSON object'],
+      ['--resource-type <resourceType>', 'Resource type key'],
+      ['--role-key <roleKey>', 'Optional role-specific scope'],
+      ['--generic', 'Create generic evidence (no roleKey)'],
+      ['--title <title>', 'Title'],
+      ['--description <description>', 'Description'],
+      ['--when <when>', 'Natural-language when condition'],
+      ['--expected-behavior <text>', 'Expected business behavior'],
+      ['--order <n>', 'Sort order within scope bucket', parseInt],
+      ['--status <status>', 'active or disabled']
+    ],
+    INSERT_HELP
+  );
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceUpdate(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'update <evidenceId>',
+    'Update an evidence row',
+    async(evidenceId, options) => runEvidenceUpdate(evidenceId, options, logger),
+    [
+      ['--file <path>', 'Partial update JSON object'],
+      ['--role-key <roleKey>', 'Role-specific scope'],
+      ['--generic', 'Clear roleKey to generic scope'],
+      ['--title <title>', 'Title'],
+      ['--description <description>', 'Description'],
+      ['--when <when>', 'When condition'],
+      ['--expected-behavior <text>', 'Expected behavior'],
+      ['--order <n>', 'Sort order', parseInt],
+      ['--status <status>', 'active or disabled']
+    ],
+    UPDATE_HELP
+  );
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceDelete(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'delete <evidenceId>',
+    'Delete evidence when it is not referenced by runtime execution',
+    async(evidenceId, options) => runEvidenceDelete(evidenceId, options, logger),
+    [['--yes', 'Skip confirmation prompt']],
+    DELETE_HELP
+  );
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceLoad(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'load',
+    'Bulk insert or update evidence rows from a JSON array file',
+    async(options) => runEvidenceLoad(options, logger),
+    [
+      ['--file <path>', `JSON array file (default: ${DEFAULT_BULK_FILE})`],
+      ['--dry-run', 'Validate file without mutating dataplane']
+    ],
+    LOAD_HELP
+  );
+}
+
+/**
+ * @param {import('commander').Command} evidence
+ */
+function registerEvidenceExport(evidence) {
+  addEvidenceLeaf(
+    evidence,
+    'export',
+    'Export filtered evidence rows to a JSON array file',
+    async(options) => runEvidenceExport(options, logger),
+    [
+      ['--file <path>', `Output file (default: ${DEFAULT_BULK_FILE})`],
+      ['--resource-type <resourceType>', 'Filter by resource type'],
+      ['--role-key <roleKey>', 'Filter by role-specific scope'],
+      ['--generic', 'Generic rows only'],
+      ['--status <status>', 'Filter by active or disabled']
+    ],
+    EXPORT_HELP
+  );
+}
+
+module.exports = {
+  registerEvidenceList,
+  registerEvidenceGet,
+  registerEvidenceInsert,
+  registerEvidenceUpdate,
+  registerEvidenceDelete,
+  registerEvidenceLoad,
+  registerEvidenceExport
+};