@aifabrix/builder 2.49.2 → 2.50.0

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

package/lib/commands/evidence.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Evidence Fabrix v2 CLI commands.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  registerEvidenceList,
+  registerEvidenceGet,
+  registerEvidenceInsert,
+  registerEvidenceUpdate,
+  registerEvidenceDelete,
+  registerEvidenceLoad,
+  registerEvidenceExport
+} = require('./evidence-cli-leaves');
+
+const EVIDENCE_HELP_AFTER = `
+
+Examples:
+  $ aifabrix evidence list --resource-type deal
+  $ aifabrix evidence insert --resource-type deal --title "Review threshold" --when "..." --expected-behavior "..."
+  $ aifabrix evidence export --file .evidence/evidence.json
+  $ aifabrix evidence load --file .evidence/evidence.json --dry-run
+  $ aifabrix evidence delete ev2_abc123 --yes
+
+Per-command help:  aifabrix evidence <command> --help
+`;
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupEvidenceCommands(program) {
+  const evidence = program
+    .command('evidence')
+    .description('Manage Evidence Fabrix v2 rows on the dataplane')
+    .addHelpText('after', EVIDENCE_HELP_AFTER);
+
+  registerEvidenceList(evidence);
+  registerEvidenceGet(evidence);
+  registerEvidenceInsert(evidence);
+  registerEvidenceUpdate(evidence);
+  registerEvidenceDelete(evidence);
+  registerEvidenceLoad(evidence);
+  registerEvidenceExport(evidence);
+}
+
+module.exports = {
+  setupEvidenceCommands
+};

package/lib/commands/governance-cli-shared.js

@@ -9,7 +9,7 @@ const {
   syncLocalIfRequested
 } = require('./test-e2e-external');
 const { resolveIntegrationAuth } = require('../external-system/integration-auth-context');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
 const { formatNetworkError } = require('../utils/api-error-handler');
 
@@ -74,7 +74,7 @@ async function resolveGovernanceIntegrationContext(systemKey, options) {
       dataplaneUrl: options.dataplaneUrl
     };
   }
-  if (!cliOptsSkipSync(options)) {
+  if (!cliOptsSkipPublish(options)) {
     const uploadCtx = await syncLocalIfRequested(resolvedKey, options);
     if (uploadCtx?.authConfig && uploadCtx?.dataplaneUrl) {
       options.authConfig = uploadCtx.authConfig;

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

@@ -35,7 +35,7 @@ function normalizeGovernanceOptions(options, cmd) {
   return {
     env: options.env || parent.env || 'dev',
     verbose: options.verbose === true || parent.verbose === true,
-    noSync: options.noSync === true || parent.noSync === true,
+    noPublish: options.noPublish === true || parent.noPublish === true,
     force: options.force === true || parent.force === true,
     json: options.json === true || parent.json === true,
     pack: options.pack,
@@ -109,7 +109,7 @@ async function governanceUploadHandler(systemKey, options, cmd) {
 async function governanceDownloadHandler(systemKey, options, cmd) {
   try {
     const opts = normalizeGovernanceOptions(options, cmd);
-    opts.noSync = true;
+    opts.noPublish = true;
     const result = await runGovernanceDownloadForExternalSystem(systemKey, opts);
     if (opts.json) {
       logger.log(JSON.stringify(buildJsonEnvelope(result, opts.verbose), null, 2));

package/lib/commands/governance-fixture-subjects.js

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Resolve governance subject emails from integration fixture CSV.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { nodeFs } = require('../internal/node-fs');
+const { getIntegrationPath } = require('../utils/paths');
+
+/**
+ * @param {string} line
+ * @returns {string[]}
+ */
+function parseCsvLine(line) {
+  const cells = [];
+  let current = '';
+  let inQuotes = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    if (char === '"') {
+      inQuotes = !inQuotes;
+      continue;
+    }
+    if (char === ',' && !inQuotes) {
+      cells.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  cells.push(current.trim());
+  return cells;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} emailIndex
+ * @returns {string[]}
+ */
+function collectUniqueEmailsFromRows(lines, emailIndex) {
+  const emails = [];
+  const seen = new Set();
+  for (let rowIndex = 1; rowIndex < lines.length; rowIndex += 1) {
+    const row = parseCsvLine(lines[rowIndex]);
+    const email = String(row[emailIndex] || '').trim().toLowerCase();
+    if (!email || seen.has(email)) {
+      continue;
+    }
+    seen.add(email);
+    emails.push(email);
+  }
+  return emails;
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {string[]}
+ */
+function resolveGovernanceFixtureSubjectEmails(systemKey) {
+  const integrationPath = getIntegrationPath(systemKey);
+  const csvPath = path.join(integrationPath, 'fixtures', 'session-users.csv');
+  const disk = nodeFs();
+  if (!disk.existsSync(csvPath)) {
+    return [];
+  }
+  const raw = disk.readFileSync(csvPath, 'utf8');
+  const lines = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.length < 2) {
+    return [];
+  }
+  const headers = parseCsvLine(lines[0]).map((header) => header.toLowerCase());
+  const emailIndex = headers.indexOf('email');
+  if (emailIndex < 0) {
+    return [];
+  }
+  return collectUniqueEmailsFromRows(lines, emailIndex);
+}
+
+module.exports = {
+  parseCsvLine,
+  resolveGovernanceFixtureSubjectEmails
+};

package/lib/commands/governance.js

@@ -21,7 +21,7 @@ const {
 
 const SHARED_OPTS = [
   ['-e, --env <env>', 'Environment: dev, tst, or pro', 'dev'],
-  ['--no-sync', 'Skip publishing local integration files before dataplane calls'],
+  ['--no-publish', 'Skip publishing local integration files before dataplane calls'],
   [
     '--force',
     'With default sync, pass force to upload (same as aifabrix upload --force)'

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

@@ -8,7 +8,7 @@
 
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 const { runLifecycleForExternalSystem } = require('./lifecycle-external');
 const { displayLifecycleReportTTY } = require('../lifecycle/report-display');
 const { VERDICT } = require('../lifecycle/product-model');
@@ -29,7 +29,7 @@ function normalizeLifecycleCliOptions(options, cmd) {
     debug: options.debug === true || has('-d') || has('--debug'),
     json: options.json === true || has('--json'),
     run: options.run === true || has('--run'),
-    noSync: cliOptsSkipSync(options, cmd),
+    noPublish: cliOptsSkipPublish(options, cmd),
     force: options.force === true || has('--force'),
     subjectUserId: options.subjectUserId || [],
     subjectEmail: options.subjectEmail || [],

package/lib/commands/lifecycle-external.js

@@ -9,7 +9,7 @@
 const { getSystemLifecycleReport, runSystemLifecycle } = require('../api/lifecycle.api');
 const { setupIntegrationTestAuth } = require('../external-system/test-auth');
 const { getConfig } = require('../core/config');
-const { cliOptsSkipSync } = require('../utils/cli-sync-options');
+const { cliOptsSkipPublish } = require('../utils/cli-sync-options');
 const { syncLocalIfRequested } = require('./test-e2e-external');
 const { runVerifyOperationsForExternalSystem } = require('./verify-operations-external');
 const { runVerifyTrustForExternalSystem } = require('./verify-trust-external');
@@ -45,7 +45,7 @@ async function resolveLifecycleDataplaneUiBaseUrl(dataplaneUrl) {
  * @returns {Promise<{ authConfig: Object, dataplaneUrl: string }>}
  */
 async function resolveLifecycleAuth(systemKey, options) {
-  if (!cliOptsSkipSync(options) && options.run === true) {
+  if (!cliOptsSkipPublish(options) && options.run === true) {
     options.lifecycleProgress?.setLabel?.('Checking config on dataplane');
     const uploadCtx = await syncLocalIfRequested(systemKey, {
       ...options,
@@ -97,7 +97,7 @@ async function runLifecycleGovernanceCombinedIfNeeded(
  * @param {Object} options
  */
 async function runMissingVerifyStepsLocally(systemKey, report, options) {
-  const runOpts = { ...options, noSync: true };
+  const runOpts = { ...options, noPublish: true };
   if (report.operations?.verdict !== VERDICT.VERIFIED) {
     await runVerifyOperationsForExternalSystem(systemKey, runOpts);
   }

package/lib/commands/manifest-cli-auth.js

@@ -0,0 +1,29 @@
+/**
+ * Resolve bearer context for manifest CLI commands.
+ *
+ * @fileoverview Uses aifabrix auth token + developer workspace root
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const { getValidatedAuthContext } = require('./auth-status');
+
+/**
+ * @returns {Promise<{ userId: string, bearerToken: string, workspaceRoot: string }>}
+ */
+async function resolveActorBearerContext() {
+  const ctx = await getValidatedAuthContext();
+  const userId = ctx.authConfig?.userId || 'cli-user';
+  const workspaceRoot = process.env.WORKSPACE_ROOT || path.join(os.homedir(), '.aifabrix', 'builder-workspaces');
+  return {
+    userId: String(userId),
+    bearerToken: ctx.authConfig.token,
+    workspaceRoot
+  };
+}
+
+module.exports = { resolveActorBearerContext };

package/lib/commands/manifest-cli-commands.js

@@ -0,0 +1,170 @@
+/**
+ * Register manifest CLI subcommands (plan 154.4).
+ *
+ * @fileoverview Keeps setupManifestCommands under max-lines-per-function
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const chalk = require('chalk');
+const { getManifestSection, listManifestSections } = require('../programmatic/manifest-get-section');
+const { patchManifestSection } = require('../programmatic/manifest-patch-section');
+const { runManifestRepair } = require('../programmatic/manifest-repair');
+const { resolveActorBearerContext } = require('./manifest-cli-auth');
+const { resolveManifestCliIntegrationPath } = require('./manifest-cli-integration-path');
+const { createWorkspaceContext, runWithWorkspaceContext } = require('../programmatic/workspace-context');
+
+/**
+ * @param {import('commander').Command} manifest
+ */
+function registerManifestSubcommands(manifest) {
+  registerManifestReadCommands(manifest);
+  registerManifestWriteCommands(manifest);
+}
+
+/**
+ * @param {import('commander').Command} manifest
+ */
+function registerManifestReadCommands(manifest) {
+  manifest
+    .command('get-section <systemKey> <sectionKey>')
+    .description('Read one governed manifest section with quality and read token')
+    .option('--datasource <key>', 'Datasource key for datasource sections')
+    .option('--json', 'Print JSON result')
+    .action(async(systemKey, sectionKey, options) => {
+      await runManifestCliAction(options, async(ctx) => {
+        printManifestResult(
+          await getManifestSection(ctx, { sectionKey, datasourceKey: options.datasource }),
+          options
+        );
+      }, systemKey);
+    });
+
+  manifest
+    .command('list-sections <systemKey>')
+    .description('List governed section keys for a workspace system')
+    .option('--json', 'Print JSON result')
+    .action(async(systemKey, options) => {
+      await runManifestCliAction(options, async(ctx) => {
+        printManifestResult(await listManifestSections(ctx), options);
+      }, systemKey);
+    });
+}
+
+/**
+ * @param {import('commander').Command} manifest
+ */
+function registerManifestWriteCommands(manifest) {
+  manifest
+    .command('patch-section <systemKey> <sectionKey>')
+    .description('Patch one governed manifest section (requires prior get-section token)')
+    .requiredOption('--intent <text>', 'Why this patch is made (audit)')
+    .option('--datasource <key>', 'Datasource key for datasource sections')
+    .option('--file <path>', 'JSON file with patch payload object')
+    .option('--mode <mode>', 'merge or replace', 'merge')
+    .option('--token <token>', 'sectionReadToken from get-section')
+    .option('--dry-run', 'Validate without writing')
+    .option('--json', 'Print JSON result')
+    .action(async(systemKey, sectionKey, options) => {
+      await runManifestCliAction(options, async(ctx) => {
+        printManifestResult(await patchFromCli(ctx, sectionKey, options), options);
+      }, systemKey);
+    });
+
+  manifest
+    .command('repair <systemKey>')
+    .description('Run explicit manifest repair hooks after section patches')
+    .requiredOption('--hooks <list>', 'Comma-separated hooks (fieldMappings,expose,rbac,...)')
+    .option('--section-key <key>', 'Section key for graph-derived ordering metadata')
+    .option('--datasource <key>', 'Datasource key for post-repair quality snapshot')
+    .option('--dry-run', 'Preview repair')
+    .option('--json', 'Print JSON result')
+    .action(async(systemKey, options) => {
+      await runManifestCliAction(options, async(ctx) => {
+        const hooks = String(options.hooks)
+          .split(',')
+          .map((h) => h.trim())
+          .filter(Boolean);
+        printManifestResult(
+          await runManifestRepair(ctx, {
+            hooks,
+            sectionKey: options.sectionKey,
+            datasourceKey: options.datasource,
+            dryRun: options.dryRun === true
+          }),
+          options
+        );
+      }, systemKey);
+    });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} sectionKey
+ * @param {Object} options
+ */
+async function patchFromCli(ctx, sectionKey, options) {
+  const patch = options.file ? JSON.parse(fs.readFileSync(options.file, 'utf8')) : {};
+  let token = options.token;
+  if (!token) {
+    const view = await getManifestSection(ctx, { sectionKey, datasourceKey: options.datasource });
+    token = view.sectionReadToken;
+  }
+  return patchManifestSection(ctx, {
+    sectionKey,
+    datasourceKey: options.datasource,
+    intent: options.intent,
+    patch,
+    mode: options.mode,
+    sectionReadToken: token,
+    dryRun: options.dryRun === true
+  });
+}
+
+/**
+ * @param {Object} result
+ * @param {Object} options
+ */
+function printManifestResult(result, options) {
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(`${chalk.green('✓ Manifest operation completed')}\n`);
+  if (result.sectionKey) {
+    process.stdout.write(`${chalk.cyan(`  section: ${result.sectionKey}`)}\n`);
+  }
+  if (result.quality) {
+    process.stdout.write(`${chalk.cyan(`  quality.score: ${result.quality.score}`)}\n`);
+  }
+  if (result.nextActions) {
+    process.stdout.write(`${chalk.cyan(`  nextActions: ${result.nextActions.join(' → ')}`)}\n`);
+  }
+}
+
+/**
+ * @param {Object} options
+ * @param {Function} fn
+ * @param {string} systemKey
+ */
+async function runManifestCliAction(options, fn, systemKey) {
+  const auth = await resolveActorBearerContext();
+  const { integrationPath } = resolveManifestCliIntegrationPath(systemKey);
+  const ctx = createWorkspaceContext({
+    userId: auth.userId,
+    systemKey,
+    bearerToken: auth.bearerToken,
+    workspaceRoot: auth.workspaceRoot,
+    integrationPath
+  });
+  await runWithWorkspaceContext(ctx, () => fn(ctx));
+}
+
+module.exports = {
+  registerManifestSubcommands,
+  printManifestResult,
+  runManifestCliAction
+};