@aifabrix/builder 2.49.1 → 2.50.0

package/lib/programmatic/run-repository-emcp.js

@@ -0,0 +1,54 @@
+/**
+ * Repository Enterprise MCP route handlers (154.1).
+ *
+ * @fileoverview Provider-neutral repository.* capabilities
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runEnterpriseMcpCapability } = require('./run-enterprise-mcp');
+const { invokeEnterpriseMcpCapability } = require('./enterprise-mcp-client');
+const { runWithWorkspaceContext } = require('./workspace-context');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ */
+async function runRepositorySync(ctx, body = {}) {
+  return runEnterpriseMcpCapability(ctx, 'repository.sync', body);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ */
+async function runRepositoryCreateReview(ctx, body = {}) {
+  return runEnterpriseMcpCapability(ctx, 'repository.createReview', body);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ */
+async function getRepositoryStatus(ctx) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const result = await invokeEnterpriseMcpCapability(ctx, 'repository.status', {});
+    return { capabilityKey: 'repository.status', result };
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ */
+async function runRepositoryDispatchPipeline(ctx, body = {}) {
+  return runEnterpriseMcpCapability(ctx, 'repository.dispatchPipeline', body);
+}
+
+module.exports = {
+  runRepositorySync,
+  runRepositoryCreateReview,
+  getRepositoryStatus,
+  runRepositoryDispatchPipeline
+};

package/lib/programmatic/run-template-workspace.js

@@ -0,0 +1,61 @@
+/**
+ * Template and workspace Enterprise MCP route handlers (154.1).
+ *
+ * @fileoverview Provider-neutral template.* and workspace.* capabilities
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { runEnterpriseMcpCapability } = require('./run-enterprise-mcp');
+const { getSystemManifest } = require('./workspace-ops');
+const { invokeEnterpriseMcpCapability } = require('./enterprise-mcp-client');
+const { runWithWorkspaceContext } = require('./workspace-context');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ */
+async function materializeTemplate(ctx, body = {}) {
+  return runEnterpriseMcpCapability(ctx, 'template.materializeWorkspace', body);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ */
+async function getWorkspaceStatus(ctx) {
+  return runWithWorkspaceContext(ctx, async() => {
+    const local = getSystemManifest(ctx);
+    let remote = null;
+    try {
+      remote = await invokeEnterpriseMcpCapability(ctx, 'workspace.status', {});
+    } catch (err) {
+      remote = { unavailable: true, message: err.message };
+    }
+    return { local, remote };
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ */
+async function runWorkspaceDiff(ctx, body = {}) {
+  return runEnterpriseMcpCapability(ctx, 'workspace.diff', body);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} body
+ */
+async function resetWorkspaceFromTemplate(ctx, body = {}) {
+  return runEnterpriseMcpCapability(ctx, 'workspace.resetFromTemplate', body);
+}
+
+module.exports = {
+  materializeTemplate,
+  getWorkspaceStatus,
+  runWorkspaceDiff,
+  resetWorkspaceFromTemplate
+};

package/lib/programmatic/run-test.js

@@ -0,0 +1,49 @@
+/**
+ * Programmatic test wrapper (unit | integration | e2e).
+ *
+ * @fileoverview POST /test
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { testExternalSystem, testExternalSystemIntegration } = require('../external-system/test');
+const { runTestE2EForExternalSystem } = require('../commands/test-e2e-external');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * @param {string} runType
+ */
+function assertRunType(runType) {
+  const allowed = new Set(['unit', 'integration', 'e2e']);
+  if (!allowed.has(runType)) {
+    throw new Error('runType must be unit, integration, or e2e');
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ */
+async function runTest(ctx, options = {}) {
+  const runType = options.runType || 'integration';
+  assertRunType(runType);
+  const merged = mergeProgrammaticOptions(ctx, { ...options, noPublish: options.noPublish === true });
+  return runWithWorkspaceContext(ctx, async() => {
+    let result;
+    if (runType === 'unit') {
+      result = await testExternalSystem(ctx.systemKey, merged);
+    } else if (runType === 'integration') {
+      result = await testExternalSystemIntegration(ctx.systemKey, merged);
+    } else {
+      result = await runTestE2EForExternalSystem(ctx.systemKey, merged);
+    }
+    touchWorkspaceMeta(ctx, { lastOperation: `test:${runType}` });
+    return result;
+  });
+}
+
+module.exports = { runTest };

package/lib/programmatic/run-upload.js

@@ -0,0 +1,63 @@
+/**
+ * Programmatic upload wrapper — full upload.js chain with workspace + Bearer injection.
+ *
+ * @fileoverview runUpload for builder-api
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { uploadExternalSystem } = require('../commands/upload');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ * @param {boolean} [options.force]
+ * @param {boolean} [options.probe]
+ * @param {boolean} [options.dryRun]
+ * @param {boolean} [options.minimal]
+ * @param {boolean} [options.verbose]
+ * @returns {Promise<Object|void>}
+ */
+async function runUpload(ctx, options = {}) {
+  const merged = mergeProgrammaticOptions(ctx, options);
+  return runWithWorkspaceContext(ctx, async() => {
+    const result = await uploadExternalSystem(ctx.systemKey, merged);
+    if (!options.dryRun) {
+      touchWorkspaceMeta(ctx, {
+        lastOperation: 'upload',
+        lastUploadId: result?.uploadId || null
+      });
+    }
+    return result;
+  });
+}
+
+/**
+ * Preview upload manifest without Dataplane mutation (no credential push).
+ *
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ * @returns {Promise<{ manifest: Object, payload: Object }>}
+ */
+async function runPreviewUpload(ctx, options = {}) {
+  const { buildValidatedUploadManifestPayload } = require('../commands/upload');
+  return runWithWorkspaceContext(ctx, async() => {
+    const built = await buildValidatedUploadManifestPayload(ctx.systemKey, {
+      force: options.force === true,
+      minimal: true,
+      quiet: true
+    });
+    touchWorkspaceMeta(ctx, { lastOperation: 'preview-upload' });
+    return built;
+  });
+}
+
+module.exports = {
+  runUpload,
+  runPreviewUpload
+};

package/lib/programmatic/run-validate.js

@@ -0,0 +1,53 @@
+/**
+ * Programmatic validate wrapper.
+ *
+ * @fileoverview POST /validate → validateExternalSystemComplete
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { validateExternalSystemComplete } = require('../validation/validate');
+const { validatePipelineConfig } = require('../api/pipeline.api');
+const { buildValidatedUploadManifestPayload } = require('../commands/upload');
+const { runWithWorkspaceContext } = require('./workspace-context');
+const { mergeProgrammaticOptions } = require('./command-options');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [options]
+ */
+async function runValidate(ctx, options = {}) {
+  const integrationPath = ctx.getIntegrationPath();
+  if (!fs.existsSync(integrationPath)) {
+    const err = new Error('System workspace not found');
+    err.statusCode = 404;
+    throw err;
+  }
+  const merged = mergeProgrammaticOptions(ctx, options);
+  return runWithWorkspaceContext(ctx, async() => {
+    const validationResult = await validateExternalSystemComplete(ctx.systemKey, { type: 'external' });
+    let pipelineValidation = null;
+    if (options.pipelineValidate === true && validationResult.valid) {
+      const { payload } = await buildValidatedUploadManifestPayload(ctx.systemKey, {
+        minimal: true,
+        quiet: true
+      });
+      const vr = await validatePipelineConfig(merged.dataplaneUrl, merged.authConfig, {
+        config: {
+          version: payload.version,
+          application: payload.application,
+          dataSources: payload.dataSources
+        }
+      });
+      pipelineValidation = vr?.data || vr;
+    }
+    touchWorkspaceMeta(ctx, { lastOperation: 'validate' });
+    return { validationResult, pipelineValidation };
+  });
+}
+
+module.exports = { runValidate };

package/lib/programmatic/run-wizard.js

@@ -0,0 +1,40 @@
+/**
+ * Programmatic wizard wrapper.
+ *
+ * @fileoverview POST /wizard → executeWizardFromConfig
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { executeWizardFromConfig } = require('../commands/wizard-headless');
+const {
+  runWithWorkspaceContext,
+  ensureIntegrationDirectory,
+  WORKSPACE_INTEGRATION_FORMAT
+} = require('./workspace-context');
+const { buildProgrammaticAuthContext } = require('./auth-config');
+const { touchWorkspaceMeta } = require('./workspace-meta');
+const { normalizeWizardConfig } = require('./wizard-config-normalize');
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} wizardConfig
+ * @param {Object} [options]
+ */
+async function runWizard(ctx, wizardConfig, options = {}) {
+  const normalizedConfig = normalizeWizardConfig(wizardConfig, ctx.systemKey);
+  const auth = buildProgrammaticAuthContext(ctx);
+  return runWithWorkspaceContext(ctx, async() => {
+    ensureIntegrationDirectory(ctx);
+    await executeWizardFromConfig(normalizedConfig, auth.dataplaneUrl, auth.authConfig, {
+      debug: options.debug === true,
+      format: WORKSPACE_INTEGRATION_FORMAT
+    });
+    touchWorkspaceMeta(ctx, { lastOperation: 'wizard' });
+    return { systemKey: ctx.systemKey, status: 'completed' };
+  });
+}
+
+module.exports = { runWizard };

package/lib/programmatic/system-key.js

@@ -0,0 +1,48 @@
+/**
+ * System key validation for builder-api workspaces.
+ *
+ * @fileoverview Sanitize external system keys (same rules as upload.js)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYSTEM_KEY_RE = /^[a-z0-9-_]+$/;
+
+/**
+ * @param {string} systemKey
+ * @returns {string}
+ */
+function assertValidSystemKey(systemKey) {
+  if (!systemKey || typeof systemKey !== 'string') {
+    throw new Error('System key is required and must be a string');
+  }
+  if (!SYSTEM_KEY_RE.test(systemKey)) {
+    throw new Error('System key must contain only lowercase letters, numbers, hyphens, and underscores');
+  }
+  return systemKey;
+}
+
+/**
+ * @param {string} userId
+ * @returns {string}
+ */
+function assertValidUserId(userId) {
+  if (!userId || typeof userId !== 'string') {
+    throw new Error('userId is required and must be a string');
+  }
+  if (userId.includes('..') || userId.includes('/') || userId.includes('\\')) {
+    throw new Error('Invalid userId');
+  }
+  if (userId.length > 256) {
+    throw new Error('Invalid userId');
+  }
+  return userId;
+}
+
+module.exports = {
+  assertValidSystemKey,
+  assertValidUserId,
+  SYSTEM_KEY_RE
+};

package/lib/programmatic/wizard-config-normalize.js

@@ -0,0 +1,118 @@
+/**
+ * Normalize Builder API wizard JSON into wizard-headless shape.
+ *
+ * @fileoverview Maps OpenAPI camelCase source types; rewrites localhost OpenAPI URLs for dataplane fetch
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @type {Readonly<Record<string, string>>} */
+const SOURCE_TYPE_MAP = Object.freeze({
+  openapiUrl: 'openapi-url',
+  openapiFile: 'openapi-file',
+  mcpServer: 'mcp-server',
+  knownPlatform: 'known-platform'
+});
+
+/**
+ * Rewrite localhost OpenAPI URLs so dataplane can fetch from the builder-api container.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function resolveOpenApiUrlForDataplaneFetch(url) {
+  if (!url || typeof url !== 'string') {
+    return url;
+  }
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+      return url;
+    }
+    const internalHost = process.env.BUILDER_API_INTERNAL_HOST || process.env.HOSTNAME;
+    const internalPort = process.env.PORT || '3005';
+    if (!internalHost) {
+      return url;
+    }
+    parsed.protocol = 'http:';
+    parsed.hostname = internalHost;
+    parsed.port = String(internalPort);
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * @param {Object} [source]
+ * @returns {Object|undefined}
+ */
+function normalizeWizardSource(source) {
+  if (!source || typeof source !== 'object') {
+    return source;
+  }
+  const type = SOURCE_TYPE_MAP[source.type] || source.type;
+  const out = { ...source, type };
+  if (type === 'openapi-url' && out.url) {
+    out.url = resolveOpenApiUrlForDataplaneFetch(out.url);
+  }
+  if (type === 'openapi-file' && out.path && !out.filePath) {
+    out.filePath = out.path;
+  }
+  return out;
+}
+
+/**
+ * @param {Object} [preferences]
+ * @returns {Object}
+ */
+function normalizeWizardPreferences(preferences = {}) {
+  const prefs = { ...preferences };
+  if (prefs.rbac === true && prefs.enableRBAC === undefined) {
+    prefs.enableRBAC = true;
+  }
+  if (prefs.expose === true && prefs.enableOpenAPIGeneration === undefined) {
+    prefs.enableOpenAPIGeneration = true;
+  }
+  if (prefs.mcp === true && prefs.enableMCP === undefined) {
+    prefs.enableMCP = true;
+  }
+  if (!prefs.intent) {
+    prefs.intent = 'general integration';
+  }
+  if (!prefs.fieldOnboardingLevel) {
+    prefs.fieldOnboardingLevel = 'full';
+  }
+  if (prefs.enableOpenAPIGeneration === undefined) {
+    prefs.enableOpenAPIGeneration = true;
+  }
+  return prefs;
+}
+
+/**
+ * @param {Object} wizardConfig
+ * @param {string} systemKey
+ * @returns {Object}
+ */
+function normalizeWizardConfig(wizardConfig, systemKey) {
+  if (!wizardConfig || typeof wizardConfig !== 'object') {
+    throw new Error('wizardConfig body is required');
+  }
+  return {
+    mode: 'create-system',
+    ...wizardConfig,
+    appName: systemKey,
+    source: normalizeWizardSource(wizardConfig.source),
+    preferences: normalizeWizardPreferences(wizardConfig.preferences)
+  };
+}
+
+module.exports = {
+  SOURCE_TYPE_MAP,
+  resolveOpenApiUrlForDataplaneFetch,
+  normalizeWizardSource,
+  normalizeWizardPreferences,
+  normalizeWizardConfig
+};

package/lib/programmatic/workspace-cleanup.js

@@ -0,0 +1,128 @@
+/**
+ * Expired workspace purge for builder-api (plan 154.0 §8).
+ *
+ * @fileoverview Draft TTL + inactive max age cleanup job
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { resolveWorkspaceRoot } = require('./workspace-context');
+const { META_FILENAME } = require('./workspace-meta');
+const { writeAccessLog } = require('./access-log');
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * @param {string} isoDate
+ * @returns {number}
+ */
+function daysSince(isoDate) {
+  return (Date.now() - new Date(isoDate).getTime()) / MS_PER_DAY;
+}
+
+/**
+ * @param {Object} meta
+ * @param {{ draftTtlDays?: number, inactiveMaxDays?: number }} options
+ * @returns {boolean}
+ */
+function shouldPurgeWorkspace(meta, options) {
+  const modified = meta.lastModifiedAt || meta.createdAt;
+  if (!modified) {
+    return false;
+  }
+  const ageDays = daysSince(modified);
+  const inactiveMaxDays = Number(options.inactiveMaxDays ?? process.env.WORKSPACE_INACTIVE_MAX_DAYS ?? 180);
+  const draftTtlDays = Number(options.draftTtlDays ?? process.env.WORKSPACE_DRAFT_TTL_DAYS ?? 90);
+  if (ageDays > inactiveMaxDays) {
+    return true;
+  }
+  if (!meta.lastUploadId && ageDays > draftTtlDays) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} metaPath
+ * @returns {Object|null}
+ */
+function readMetaFile(metaPath) {
+  if (!fs.existsSync(metaPath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+}
+
+/**
+ * @param {string} integrationRoot
+ * @param {string} userId
+ * @param {Object} options
+ * @param {boolean} dryRun
+ * @param {Object[]} purged
+ */
+function collectExpiredSystemsUnderUser(integrationRoot, userId, options, dryRun, purged) {
+  for (const systemKey of fs.readdirSync(integrationRoot)) {
+    const systemPath = path.join(integrationRoot, systemKey);
+    if (!fs.statSync(systemPath).isDirectory()) {
+      continue;
+    }
+    const meta = readMetaFile(path.join(systemPath, META_FILENAME));
+    if (!meta || !shouldPurgeWorkspace(meta, options)) {
+      continue;
+    }
+    if (!dryRun) {
+      fs.rmSync(systemPath, { recursive: true, force: true });
+    }
+    purged.push({
+      userId,
+      systemKey,
+      lastModifiedAt: meta.lastModifiedAt,
+      lastUploadId: meta.lastUploadId ?? null
+    });
+  }
+}
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.workspaceRoot]
+ * @param {number} [options.draftTtlDays]
+ * @param {number} [options.inactiveMaxDays]
+ * @param {boolean} [options.dryRun]
+ * @returns {{ purged: Object[], count: number, dryRun: boolean }}
+ */
+function purgeExpiredWorkspaces(options = {}) {
+  const workspaceRoot = resolveWorkspaceRoot(options.workspaceRoot);
+  const dryRun = options.dryRun === true;
+  const purged = [];
+
+  if (!fs.existsSync(workspaceRoot)) {
+    return { purged, count: 0, dryRun };
+  }
+
+  for (const userId of fs.readdirSync(workspaceRoot)) {
+    const integrationRoot = path.join(workspaceRoot, userId, 'integration');
+    if (!fs.existsSync(integrationRoot)) {
+      continue;
+    }
+    collectExpiredSystemsUnderUser(integrationRoot, userId, options, dryRun, purged);
+  }
+
+  writeAccessLog({
+    event: 'workspaceCleanup',
+    count: purged.length,
+    dryRun,
+    purgedSystemKeys: purged.map((row) => `${row.userId}/${row.systemKey}`)
+  });
+
+  return { purged, count: purged.length, dryRun };
+}
+
+module.exports = {
+  purgeExpiredWorkspaces,
+  shouldPurgeWorkspace,
+  daysSince
+};