@aifabrix/builder 2.49.2 → 2.51.0

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

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

@@ -0,0 +1,63 @@
+/**
+ * Resolve on-disk integration path for manifest CLI (plan 141).
+ *
+ * @fileoverview cwd/integration → cwd/builder → ~/.aifabrix materialization
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { resolveApplicationManifestPathSync } = require('../utils/manifest-location');
+const { getIntegrationPath } = require('../utils/paths');
+const { findIntegrationPathAcrossWorkTree } = require('../utils/integration-path-resolve');
+const { discoverIntegrationFiles } = require('./repair-internal');
+
+/**
+ * @param {string} systemKey
+ * @returns {{ integrationPath: string, tier: string }}
+ */
+function resolveManifestCliIntegrationPath(systemKey) {
+  const manifestHit = resolveApplicationManifestPathSync({ targetKey: systemKey, mode: 'auto' });
+  if (manifestHit) {
+    return { integrationPath: manifestHit.absolutePath, tier: manifestHit.tier };
+  }
+
+  const fallback = getIntegrationPath(systemKey);
+  if (fs.existsSync(fallback)) {
+    const { systemFiles, datasourceFiles } = discoverIntegrationFiles(fallback);
+    if (systemFiles.length > 0 || datasourceFiles.length > 0) {
+      return { integrationPath: fallback, tier: 'paths-fallback' };
+    }
+  }
+
+  const workHit = findIntegrationPathAcrossWorkTree(systemKey);
+  if (workHit) {
+    return workHit;
+  }
+
+  const err = new Error(
+    `Integration "${systemKey}" not found. Looked under cwd/integration/${systemKey}/, ` +
+      'aifabrix-work sibling repos (*/integration/), and materialized ~/.aifabrix/.../integration/. ' +
+      'Run from the repo that contains the integration, set aifabrix-work, or set WORKSPACE_ROOT for builder-api workspaces.'
+  );
+  err.statusCode = 404;
+  throw err;
+}
+
+/**
+ * @param {string} integrationPath
+ * @param {string} systemKey
+ */
+function assertIntegrationPathMatchesSystemKey(integrationPath, systemKey) {
+  if (path.basename(path.resolve(integrationPath)) !== systemKey) {
+    throw new Error(`integrationPath must end with systemKey "${systemKey}"`);
+  }
+}
+
+module.exports = {
+  resolveManifestCliIntegrationPath,
+  assertIntegrationPathMatchesSystemKey
+};

package/lib/commands/manifest.js

@@ -0,0 +1,21 @@
+/**
+ * CLI manifest command group (plan 154.4).
+ *
+ * @fileoverview Thin wrapper registering manifest subcommands
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { registerManifestSubcommands } = require('./manifest-cli-commands');
+
+/**
+ * @param {import('commander').Command} program
+ */
+function setupManifestCommands(program) {
+  const manifest = program.command('manifest').description('Governed manifest section editing (get, patch, repair)');
+  registerManifestSubcommands(manifest);
+}
+
+module.exports = { setupManifestCommands };

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

@@ -47,7 +47,7 @@ const PROTECTION_UPLOAD_HELP_AFTER = `
 Examples:
   $ aifabrix protection upload hubspot-companies
   $ aifabrix protection upload hubspot-companies --dry-run
-  $ aifabrix protection upload hubspot-companies --no-sync
+  $ aifabrix protection upload hubspot-companies --sync
 `;
 
 const PROTECTION_LIST_HELP_AFTER = `
@@ -194,13 +194,13 @@ function registerProtectionUpload(protection) {
         manifestPath: resolved.manifestPath,
         warningsAsErrors: options.warningsAsErrors === true,
         dryRun: options.dryRun === true,
-        noSync: options.noSync === true,
+        sync: options.sync === true,
         verbose: options.verbose === true
       }, logger);
     },
     [
       ['--dry-run', 'Validate only; no upload or sync'],
-      ['--no-sync', 'Skip datasource sync after upload']
+      ['--sync', 'Force full datasource data sync after upload (default: bootstrap-if-empty)']
     ],
     PROTECTION_UPLOAD_HELP_AFTER
   );

package/lib/commands/repair-auth-apply.js

@@ -27,7 +27,8 @@ const ALLOWED_REPAIR_AUTH = [
   'queryparam',
   'oidc',
   'hmac',
-  'none'
+  'none',
+  'bearerforward'
 ];
 
 const PRESERVED_VARIABLE_KEYS = ['baseUrl', 'testEndpoint'];
@@ -56,6 +57,9 @@ function isAllowedRepairAuth(authOption) {
  */
 function buildAuthenticationForRepair(systemKey, authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
+  if (normalized === 'bearerforward') {
+    return buildBearerForwardAuthentication();
+  }
   const schemaMethod =
     normalized === 'queryparam'
       ? 'queryParam'
@@ -65,6 +69,14 @@ function buildAuthenticationForRepair(systemKey, authOption) {
   return buildAuthenticationFromMethod(systemKey, schemaMethod);
 }
 
+/**
+ * Facade APIs that forward the caller Bearer token — no workspace kv secret.
+ * @returns {{ authType: 'none' }}
+ */
+function buildBearerForwardAuthentication() {
+  return { authType: 'none' };
+}
+
 /**
  * Merges preserved connectivity fields from existing auth into template variables.
  * @param {Object} mergedVariables - Target variables object (mutated)
@@ -87,6 +99,7 @@ function mergePreservedAuthVariables(mergedVariables, existingVars) {
 function repairAuthChangeLabel(authOption) {
   const normalized = normalizeRepairAuthOption(authOption);
   if (normalized === 'bearertoken' || normalized === 'bearerkey') return 'bearerToken';
+  if (normalized === 'bearerforward') return 'bearerForward';
   return normalized;
 }
 
@@ -144,6 +157,7 @@ module.exports = {
   normalizeRepairAuthOption,
   isAllowedRepairAuth,
   buildAuthenticationForRepair,
+  buildBearerForwardAuthentication,
   mergePreservedAuthVariables,
   repairAuthChangeLabel,
   appendTestEndpointWarningIfMissing,

package/lib/commands/repair-authentications-454.js

@@ -0,0 +1,169 @@
+/**
+ * Repair authentications[] normalization for 454.0 webhooks/syncBridge.
+ *
+ * @fileoverview Normalize legacy authentication to authentications[] slots
+ */
+
+'use strict';
+
+const { migrateAuthenticationToNestedSchema } = require('../utils/authentication-shape');
+
+const AUTH_USAGE_API = 'api';
+const AUTH_USAGE_WEBHOOK_INBOUND = 'webhookInbound';
+const AUTH_USAGE_SYNC_EXECUTION = 'syncExecution';
+
+/**
+ * @param {string} systemKey
+ * @returns {object}
+ */
+function buildWebhookInboundAuthSlot(systemKey) {
+  const key = systemKey || 'system';
+  return {
+    key: 'webhookInbound',
+    usage: AUTH_USAGE_WEBHOOK_INBOUND,
+    authType: 'credential',
+    credential: {
+      credentialKey: `${key}-webhook-inbound`,
+      method: 'hmac',
+      variables: {
+        algorithm: 'sha256',
+        signatureHeader: 'X-Webhook-Signature',
+        timestampHeader: 'X-Webhook-Timestamp',
+        signaturePrefix: 'v0='
+      },
+      security: {
+        signingSecret: `kv://${key}/webhookInbound/signingSecret`
+      }
+    }
+  };
+}
+
+/**
+ * @param {string} systemKey
+ * @returns {object}
+ */
+function buildSyncExecutionAuthSlot(systemKey) {
+  const key = systemKey || 'system';
+  return {
+    key: 'syncExecution',
+    usage: AUTH_USAGE_SYNC_EXECUTION,
+    authType: 'credential',
+    credential: {
+      credentialKey: `${key}-sync-execution`,
+      method: 'apikey',
+      variables: {
+        baseUrl: 'https://api.example.com',
+        headerName: 'X-API-Key',
+        testEndpoint: '/health'
+      },
+      security: {
+        apiKey: `kv://${key}/syncExecution/apiKey`
+      }
+    }
+  };
+}
+
+/**
+ * Normalize legacy authentication to authentications[] when missing.
+ * @param {object} systemJson - Parsed external system manifest
+ * @returns {{ changed: boolean, warnings: string[] }}
+ */
+function repairAuthenticationsArray(systemJson) {
+  const warnings = [];
+  if (!systemJson || typeof systemJson !== 'object') {
+    return { changed: false, warnings };
+  }
+
+  migrateAuthenticationToNestedSchema(systemJson);
+
+  const existing = systemJson.authentications;
+  if (Array.isArray(existing) && existing.length > 0) {
+    return { changed: false, warnings };
+  }
+
+  const legacy = systemJson.authentication;
+  if (!legacy || typeof legacy !== 'object') {
+    return { changed: false, warnings };
+  }
+
+  systemJson.authentications = [
+    {
+      key: 'default',
+      usage: AUTH_USAGE_API,
+      ...legacy
+    }
+  ];
+  warnings.push(
+    'Normalized legacy authentication to authentications[{key:default, usage:api}].'
+  );
+  return { changed: true, warnings };
+}
+
+/**
+ * Ensure webhook/sync auth slots exist when repair flags request them.
+ * @param {object} systemJson
+ * @param {{ authWebhook?: boolean, authSync?: boolean, systemKey: string, authMethod?: string }} options
+ * @returns {{ changed: boolean, warnings: string[] }}
+ */
+function ensureAuthUsageSlots(systemJson, options) {
+  const warnings = [];
+  const { repairAuthenticationsArray: normalize } = { repairAuthenticationsArray };
+  const base = normalize(systemJson);
+  warnings.push(...base.warnings);
+  let changed = base.changed;
+
+  if (!Array.isArray(systemJson.authentications)) {
+    systemJson.authentications = [];
+  }
+
+  const ensureSlot = (usage, slotKey, slotFactory) => {
+    const found = systemJson.authentications.some(
+      (row) => row && row.usage === usage
+    );
+    if (found) {
+      return;
+    }
+    if (typeof slotFactory === 'function') {
+      systemJson.authentications.push(slotFactory(options.systemKey));
+      warnings.push(`Added authentications slot usage=${usage} key=${slotKey}.`);
+      changed = true;
+      return;
+    }
+    const template = systemJson.authentications[0] || systemJson.authentication;
+    if (!template || typeof template !== 'object') {
+      warnings.push(`Cannot add ${usage} slot — no authentication template available.`);
+      return;
+    }
+    const { key: _ignored, usage: _u, ...rest } = template;
+    systemJson.authentications.push({ key: slotKey, usage, ...rest });
+    warnings.push(`Added authentications slot usage=${usage} key=${slotKey}.`);
+    changed = true;
+  };
+
+  if (options.authWebhook) {
+    ensureSlot(
+      AUTH_USAGE_WEBHOOK_INBOUND,
+      'webhookInbound',
+      buildWebhookInboundAuthSlot
+    );
+  }
+  if (options.authSync) {
+    ensureSlot(
+      AUTH_USAGE_SYNC_EXECUTION,
+      'syncExecution',
+      buildSyncExecutionAuthSlot
+    );
+  }
+
+  return { changed, warnings };
+}
+
+module.exports = {
+  repairAuthenticationsArray,
+  ensureAuthUsageSlots,
+  buildWebhookInboundAuthSlot,
+  buildSyncExecutionAuthSlot,
+  AUTH_USAGE_API,
+  AUTH_USAGE_WEBHOOK_INBOUND,
+  AUTH_USAGE_SYNC_EXECUTION
+};

package/lib/commands/repair-capability-openapi-warnings.js

@@ -0,0 +1,126 @@
+/**
+ * Warn when datasource capabilities lack matching openapi.operations (autoRbac).
+ *
+ * @fileoverview repair-capability-openapi-warnings
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { loadConfigFile } = require('../utils/config-format');
+const { capabilityKeysFromManifest } = require('./repair-datasource-sync-operations');
+
+/**
+ * @param {string} opKey
+ * @returns {string}
+ */
+function normalizeRbacOperationKey(opKey) {
+  const s = typeof opKey === 'string' ? opKey.trim() : '';
+  if (!s) return '';
+  if (/^[a-z][a-zA-Z0-9]*$/.test(s)) return s.toLowerCase();
+  const withHyphens = s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+  const cleaned = withHyphens.replace(/[^a-z0-9-]+/g, '-');
+  return cleaned.replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {boolean}
+ */
+function hasAutoRbacOpenApi(parsed) {
+  const openapi = parsed?.openapi;
+  return (
+    openapi &&
+    typeof openapi === 'object' &&
+    openapi.autoRbac === true &&
+    openapi.operations &&
+    typeof openapi.operations === 'object' &&
+    !Array.isArray(openapi.operations)
+  );
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {Set<string>}
+ */
+function normalizedOpenApiOperationKeys(parsed) {
+  const ops = parsed?.openapi?.operations;
+  const out = new Set();
+  if (!ops || typeof ops !== 'object') {
+    return out;
+  }
+  for (const key of Object.keys(ops)) {
+    const norm = normalizeRbacOperationKey(key) || key;
+    if (norm) out.add(norm);
+  }
+  return out;
+}
+
+/**
+ * @param {Object} parsed
+ * @returns {string[]}
+ */
+function findCapabilityKeysMissingFromOpenApi(parsed) {
+  if (!hasAutoRbacOpenApi(parsed)) {
+    return [];
+  }
+  const capKeys = capabilityKeysFromManifest(parsed?.capabilities);
+  if (capKeys.length === 0) {
+    return [];
+  }
+  const openApiKeys = normalizedOpenApiOperationKeys(parsed);
+  return capKeys.filter((key) => !openApiKeys.has(normalizeRbacOperationKey(key) || key));
+}
+
+/**
+ * @param {string} fileName
+ * @param {Object} parsed
+ * @param {string[]} missingKeys
+ * @returns {string}
+ */
+function formatCapabilityOpenApiDriftWarning(fileName, parsed, missingKeys) {
+  const dsKey = typeof parsed?.key === 'string' && parsed.key.trim() ? parsed.key.trim() : fileName;
+  return (
+    `${dsKey}: capabilities declare ${missingKeys.join(', ')} but openapi.operations is missing them — ` +
+    'RBAC repair may omit matching permissions; operations sync runs automatically with --rbac'
+  );
+}
+
+/**
+ * @param {string} appPath
+ * @param {string[]} datasourceFiles
+ * @param {string[]} warnings
+ * @returns {number}
+ */
+function collectCapabilityOpenApiDriftWarnings(appPath, datasourceFiles, warnings) {
+  if (!Array.isArray(warnings) || !Array.isArray(datasourceFiles)) {
+    return 0;
+  }
+  let count = 0;
+  for (const fileName of datasourceFiles) {
+    const filePath = path.join(appPath, fileName);
+    if (!fs.existsSync(filePath)) continue;
+    let parsed;
+    try {
+      parsed = loadConfigFile(filePath);
+    } catch {
+      continue;
+    }
+    const missingKeys = findCapabilityKeysMissingFromOpenApi(parsed);
+    if (missingKeys.length === 0) continue;
+    warnings.push(formatCapabilityOpenApiDriftWarning(fileName, parsed, missingKeys));
+    count += 1;
+  }
+  return count;
+}
+
+module.exports = {
+  normalizeRbacOperationKey,
+  hasAutoRbacOpenApi,
+  findCapabilityKeysMissingFromOpenApi,
+  collectCapabilityOpenApiDriftWarnings,
+  formatCapabilityOpenApiDriftWarning
+};