@aifabrix/builder 2.49.1 → 2.50.0

package/lib/programmatic/builder-help-connected-system-ui.js

@@ -0,0 +1,266 @@
+/**
+ * Connected Systems UI URL catalog for builder-api LLM help (plan 154.6).
+ *
+ * @fileoverview Structured paths and tab aliases for post-upload authentication handoff
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { buildHelpEnvelope } = require('./builder-help-envelope');
+const {
+  buildAuthenticationCatalog,
+  buildAuthenticationHandoffForManifest
+} = require('./builder-help-authentication-catalog');
+
+/** @type {ReadonlyArray<Object>} */
+const SYSTEM_TABS = Object.freeze([
+  { uiLabel: 'Overview', urlTab: null, aliases: ['overview'], omitTabParam: true },
+  { uiLabel: 'Technical readiness', urlTab: 'technical-readiness', aliases: [] },
+  { uiLabel: 'Business Entities', urlTab: 'datasources', aliases: ['business-entities'] },
+  { uiLabel: 'Business Policies', urlTab: 'rules', aliases: ['business-policies'] },
+  { uiLabel: 'Authentication', urlTab: 'authentication', aliases: ['Authentication'] },
+  { uiLabel: 'Configuration', urlTab: 'configuration', aliases: [] },
+  { uiLabel: 'AI Interfaces', urlTab: 'openapi', aliases: ['ai-interfaces'] },
+  { uiLabel: 'Policies & Security', urlTab: 'policies', aliases: [], note: 'When policy management is enabled in dataplane.' },
+  { uiLabel: 'Audit & History', urlTab: 'audit', aliases: ['audit-history'] }
+]);
+
+/** @type {ReadonlyArray<Object>} */
+const DATASOURCE_TABS = Object.freeze([
+  {
+    uiLabel: 'Overview',
+    urlTab: 'business-context',
+    aliases: ['business-overview'],
+    omitTabParam: true,
+    note: 'First tab id is business-context. URL value overview opens Technical readiness.'
+  },
+  { uiLabel: 'Technical readiness', urlTab: 'overview', aliases: ['technical-readiness'] },
+  { uiLabel: 'Data Flow', urlTab: 'cip', aliases: ['data-flow', 'Data Flow'] },
+  { uiLabel: 'Business Vocabulary', urlTab: 'mappings', aliases: ['business-vocabulary'] },
+  { uiLabel: 'AI Contract', urlTab: 'exposure', aliases: ['ai-contract'] },
+  { uiLabel: 'Business Policies', urlTab: 'abac', aliases: ['business-policies'] },
+  { uiLabel: 'Quality', urlTab: 'quality', aliases: [] },
+  { uiLabel: 'Sync', urlTab: 'sync', aliases: [] },
+  { uiLabel: 'Doc Processing', urlTab: 'document-processing', aliases: ['doc-processing'] },
+  { uiLabel: 'Operations', urlTab: 'openapi', aliases: ['operations'] },
+  { uiLabel: 'Configuration', urlTab: 'configuration', aliases: [] },
+  { uiLabel: 'YAML', urlTab: 'yaml', aliases: [] },
+  { uiLabel: 'Logs', urlTab: 'logs', aliases: ['audit-logs', 'execution-logs'] }
+]);
+
+/** @type {Readonly<Object>} */
+const URL_TEMPLATES = Object.freeze({
+  dataplanePublicBasePlaceholder: '{dataplanePublicBase}',
+  systemPath: '/connected-systems/{systemKey}',
+  systemPathWithTab: '/connected-systems/{systemKey}?tab={tab}',
+  datasourcePath: '/connected-systems/{systemKey}/datasources/{datasourceKey}',
+  datasourcePathWithTab: '/connected-systems/{systemKey}/datasources/{datasourceKey}?tab={tab}',
+  composedSystemUrl: '{dataplanePublicBase}/connected-systems/{systemKey}?tab={tab}',
+  composedDatasourceUrl:
+    '{dataplanePublicBase}/connected-systems/{systemKey}/datasources/{datasourceKey}?tab={tab}',
+  routeHelper:
+    'Dataplane UI route helper: CONNECTED_SYSTEM_ROUTES.DATASOURCE_TAB(systemKey, datasourceKey, tab).'
+});
+
+/** @type {ReadonlyArray<string>} */
+const AGENT_RULES = Object.freeze([
+  'Run validate, test, test-integration, and upload without requiring resolved integration secrets in Builder API scope.',
+  'Upload publishes manifest authentication.credential.variables (non-secrets) pre-filled in the UI; kv:// security placeholders stay unresolved until the user adds live secrets.',
+  'Before post-upload handoff, read system.authentications[] (or legacy authentication) and identify authType, usage (api, webhookInbound, syncExecution), and credential.method when applicable.',
+  'Set all non-secret auth config in credential.variables during manifest editing — do not ask the user to re-enter baseUrl, headerName, tokenUrl, or similar after upload.',
+  'After upload succeeds, ask the user to open Connected Systems Authentication and add only requiredSecretKeys (for example apiKey token, webhookInbound signingSecret) — not variables already published.',
+  'When webhook.enabled or syncBridge is active, direct the user to datasource Sync tab (tab=sync) for webhook activation markdown and syncBridge read-only status.',
+  'Combine the user dataplane public base (origin including /data) with paths from urlTemplates.',
+  'Do not ask the user to paste vendor tokens into Builder API requests or workspace files when UI authentication is the intended path.',
+  'Tab query values are case-insensitive; aliases in systemTabs and datasourceTabs are accepted on load.'
+]);
+
+/** @type {ReadonlyArray<Object>} */
+const POST_UPLOAD_AUTH_WORKFLOW = Object.freeze([
+  { order: 1, capability: 'validate', goal: 'Confirm workspace manifest structure before publish.' },
+  { order: 2, capability: 'test', goal: 'Run local manifest tests without live vendor credentials.' },
+  {
+    order: 3,
+    capability: 'test-integration',
+    goal: 'Exercise pipeline integration tests; credential gaps may remain until UI auth is set.'
+  },
+  {
+    order: 4,
+    capability: 'upload',
+    goal: 'Publish external system draft without embedding resolved secrets in the workspace.'
+  },
+  {
+    order: 5,
+    capability: 'ui-authentication-handoff',
+    goal:
+      'Read authentications[] usage slots and credential.method from manifest; provide Authentication URL and method-specific secret field guidance from authentication catalog. Include webhookInbound and syncExecution when configured.'
+  },
+  {
+    order: 6,
+    capability: 'ui-sync-fabrix-handoff',
+    goal:
+      'When webhook or syncBridge is enabled, provide datasource Sync tab URL (tab=sync) for activation guide and read-only fabrix status.'
+  },
+  { order: 7, capability: 'test-e2e', goal: 'After UI auth is configured, user or agent re-runs E2E against live vendor APIs.' }
+]);
+
+/**
+ * @param {string} input
+ * @param {ReadonlyArray<Object>} catalog
+ * @returns {string|null}
+ */
+function resolveTabFromCatalog(input, catalog) {
+  if (!input) {
+    return null;
+  }
+  const normalized = String(input).toLowerCase();
+  for (const entry of catalog) {
+    if (entry.urlTab && entry.urlTab.toLowerCase() === normalized) {
+      return entry.urlTab;
+    }
+    for (const alias of entry.aliases || []) {
+      if (String(alias).toLowerCase() === normalized) {
+        return entry.urlTab;
+      }
+    }
+    if (entry.omitTabParam && normalized === 'overview') {
+      return null;
+    }
+  }
+  return String(input);
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string|null|undefined} tabInput
+ * @returns {string}
+ */
+function buildSystemRelativePath(systemKey, tabInput) {
+  const encodedKey = encodeURIComponent(systemKey);
+  const tab = resolveTabFromCatalog(tabInput, SYSTEM_TABS);
+  const base = `/connected-systems/${encodedKey}`;
+  if (!tab) {
+    return base;
+  }
+  return `${base}?tab=${encodeURIComponent(tab)}`;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string} datasourceKey
+ * @param {string|null|undefined} tabInput
+ * @returns {string}
+ */
+function buildDatasourceRelativePath(systemKey, datasourceKey, tabInput) {
+  const tab = resolveTabFromCatalog(tabInput, DATASOURCE_TABS);
+  const base = `/connected-systems/${encodeURIComponent(systemKey)}/datasources/${encodeURIComponent(datasourceKey)}`;
+  if (!tab) {
+    return base;
+  }
+  return `${base}?tab=${encodeURIComponent(tab)}`;
+}
+
+/**
+ * @param {string} publicBase
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function composePublicUrl(publicBase, relativePath) {
+  const trimmedBase = String(publicBase).replace(/\/$/, '');
+  const trimmedPath = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+  return `${trimmedBase}${trimmedPath}`;
+}
+
+/**
+ * @param {Object} data
+ * @param {Object} params
+ * @returns {void}
+ */
+function attachConnectedSystemResolvedPaths(data, params) {
+  const { systemKey, tab, datasourceKey, datasourceTab, publicBase } = params;
+  const authenticationPath = buildSystemRelativePath(systemKey, 'authentication');
+  const requestedSystemPath = buildSystemRelativePath(systemKey, tab);
+  data.resolved = {
+    systemKey,
+    authenticationPath,
+    requestedSystemPath
+  };
+  if (publicBase) {
+    data.resolved.authenticationUrl = composePublicUrl(publicBase, authenticationPath);
+    data.resolved.requestedSystemUrl = composePublicUrl(publicBase, requestedSystemPath);
+  }
+  if (datasourceKey) {
+    const datasourcePath = buildDatasourceRelativePath(systemKey, datasourceKey, datasourceTab);
+    data.resolved.datasourceKey = datasourceKey;
+    data.resolved.datasourcePath = datasourcePath;
+    if (publicBase) {
+      data.resolved.datasourceUrl = composePublicUrl(publicBase, datasourcePath);
+    }
+  }
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildConnectedSystemUiTopic(query) {
+  const systemKey = query.systemKey ? String(query.systemKey) : null;
+  const datasourceKey = query.datasourceKey ? String(query.datasourceKey) : null;
+  const tab = query.tab || 'authentication';
+  const datasourceTab = query.datasourceTab || null;
+  const publicBase = query.dataplanePublicBase ? String(query.dataplanePublicBase) : null;
+
+  /** @type {Object} */
+  const data = {
+    urlTemplates: URL_TEMPLATES,
+    systemTabs: SYSTEM_TABS,
+    datasourceTabs: DATASOURCE_TABS,
+    authentication: buildAuthenticationCatalog(),
+    agentRules: AGENT_RULES,
+    postUploadAuthWorkflow: POST_UPLOAD_AUTH_WORKFLOW,
+    behavior: {
+      tabQuerySelectsTabOnLoad: true,
+      tabSwitchUpdatesUrl: true,
+      navigationClearsStaleTabState: true,
+      staticUiRebuildNote: 'Rebuild dataplane static UI after UI route changes when using Docker dev-reload (make ui-build).'
+    }
+  };
+
+  const manifestHandoff = buildAuthenticationHandoffForManifest(query);
+  if (manifestHandoff) {
+    data.manifestHandoff = manifestHandoff;
+  }
+
+  if (systemKey) {
+    attachConnectedSystemResolvedPaths(data, {
+      systemKey,
+      tab,
+      datasourceKey,
+      datasourceTab,
+      publicBase
+    });
+  }
+
+  return buildHelpEnvelope({
+    topic: 'connectedSystemUi',
+    key: systemKey || 'connectedSystemUi',
+    title: 'Connected Systems UI navigation',
+    summary:
+      'Shareable dataplane UI paths, tab aliases, and external-system authentication catalog for post-upload handoff without Builder API secrets.',
+    data,
+    related: ['workflow', 'subscriptionGuide', 'evidencePatterns'],
+    recommendedNext: ['workflow', 'evidencePatterns']
+  });
+}
+
+module.exports = {
+  SYSTEM_TABS,
+  DATASOURCE_TABS,
+  URL_TEMPLATES,
+  buildSystemRelativePath,
+  buildDatasourceRelativePath,
+  composePublicUrl,
+  buildConnectedSystemUiTopic
+};

package/lib/programmatic/builder-help-enterprise-sync-fabrix.js

@@ -0,0 +1,60 @@
+/**
+ * Enterprise Synchronization Fabrix help topic (webhooks + syncBridge).
+ *
+ * @fileoverview Builder-api LLM help for webhook activation and syncBridge
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { buildHelpEnvelope } = require('./builder-help-envelope');
+
+const HELP_MD_DIR = path.join(__dirname, 'help-content');
+
+/** @type {ReadonlyArray<string>} */
+const REPAIR_COMMANDS = Object.freeze([
+  'aifabrix repair <systemKey>',
+  'aifabrix repair <systemKey> --auth <method>',
+  'aifabrix repair <systemKey> --auth-webhook',
+  'aifabrix repair <systemKey> --auth-sync',
+  'aifabrix validate <app>',
+  'aifabrix upload <app>'
+]);
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildEnterpriseSyncFabrixTopic(query) {
+  const raw = fs.readFileSync(
+    path.join(HELP_MD_DIR, 'enterprise-sync-fabrix.md'),
+    'utf8'
+  );
+  const systemKey = query.systemKey ? String(query.systemKey) : '';
+  return buildHelpEnvelope({
+    topic: 'enterpriseSyncFabrix',
+    key: systemKey || 'enterpriseSyncFabrix',
+    title: 'Enterprise Synchronization Fabrix',
+    summary:
+      'Webhook change signals, syncBridge propagation, authentications[] usage slots, and activation workflow.',
+    data: {
+      authenticationsUsageSlots: ['api', 'webhookInbound', 'syncExecution'],
+      syncBridgeModes: ['disabled', 'master', 'bidirectional'],
+      webhookEndpointModes: ['system', 'datasource', 'event'],
+      repairCommands: [...REPAIR_COMMANDS],
+      postUploadTabs: {
+        systemAuthentication: 'authentication',
+        datasourceSync: 'sync',
+        datasourceLogs: 'logs'
+      },
+      bodyText: raw.replace(/\s{2,}/g, ' ').trim()
+    },
+    related: ['connectedSystemUi', 'workflow', 'schemaCatalog'],
+    recommendedNext: ['connectedSystemUi', 'workflow']
+  });
+}
+
+module.exports = {
+  buildEnterpriseSyncFabrixTopic
+};

package/lib/programmatic/builder-help-envelope.js

@@ -0,0 +1,36 @@
+/**
+ * Help response envelope builder (plan 154.5).
+ *
+ * @fileoverview Shared constants and envelope shape for builder-api help
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const HELP_CONTENT_VERSION = '154.7';
+const HELP_SCHEMA_VERSION = '1.0.0';
+
+/**
+ * @param {Object} input
+ * @returns {Object}
+ */
+function buildHelpEnvelope(input) {
+  return {
+    version: HELP_CONTENT_VERSION,
+    schemaVersion: HELP_SCHEMA_VERSION,
+    topic: input.topic,
+    key: input.key,
+    title: input.title,
+    summary: input.summary,
+    data: input.data || {},
+    related: input.related || [],
+    recommendedNext: input.recommendedNext || []
+  };
+}
+
+module.exports = {
+  HELP_CONTENT_VERSION,
+  HELP_SCHEMA_VERSION,
+  buildHelpEnvelope
+};

package/lib/programmatic/builder-help-fixtures.js

@@ -0,0 +1,200 @@
+/**
+ * Golden examples and evidence pattern loaders for builder-api help (plan 154.6).
+ *
+ * @fileoverview Fixture-backed help topics
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { buildHelpEnvelope } = require('./builder-help-envelope');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const GOLDEN_DIR = path.join(REPO_ROOT, 'docs', 'builder-help', 'golden-examples');
+const EVIDENCE_PATH = path.join(REPO_ROOT, 'docs', 'builder-help', 'evidence-patterns.json');
+
+/** @type {Record<string, Object>|null} */
+let evidenceCache = null;
+/** @type {Record<string, Object>|null} */
+let goldenCache = null;
+
+/**
+ * @param {string} message
+ * @returns {Error}
+ */
+function validationError(message) {
+  const err = new Error(message);
+  err.statusCode = 400;
+  return err;
+}
+
+/**
+ * @param {string} message
+ * @returns {Error}
+ */
+function notFoundError(message) {
+  const err = new Error(message);
+  err.statusCode = 404;
+  return err;
+}
+
+/**
+ * @returns {Record<string, Object>}
+ */
+function loadGoldenExamplesMap() {
+  if (goldenCache) {
+    return goldenCache;
+  }
+  /** @type {Record<string, Object>} */
+  const map = {};
+  for (const file of fs.readdirSync(GOLDEN_DIR).sort()) {
+    if (!file.endsWith('.json')) {
+      continue;
+    }
+    const doc = JSON.parse(fs.readFileSync(path.join(GOLDEN_DIR, file), 'utf8'));
+    map[doc.key || path.basename(file, '.json')] = doc;
+  }
+  goldenCache = map;
+  return map;
+}
+
+/**
+ * @param {Object} item
+ * @param {Object} query
+ * @returns {boolean}
+ */
+function matchesResourceRoleFilter(item, query) {
+  if (query.resourceType && item.resourceType !== query.resourceType) {
+    return false;
+  }
+  if (query.role && item.role !== query.role) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildGoldenExamplesTopic(query) {
+  const map = loadGoldenExamplesMap();
+  const examples = Object.values(map)
+    .filter((item) => matchesResourceRoleFilter(item, query))
+    .map((item) => ({
+      key: item.key,
+      title: item.title,
+      summary: item.summary,
+      resourceType: item.resourceType,
+      role: item.role,
+      roleAssistantExamples: item.roleAssistantExamples || [],
+      recommendedSectionKeys: item.recommendedSectionKeys || []
+    }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+  return buildHelpEnvelope({
+    topic: 'goldenExamples',
+    key: 'goldenExamples',
+    title: 'Golden manifest examples',
+    summary: 'Reference patterns for common external integration shapes.',
+    data: { examples },
+    related: ['goldenExample', 'workflow', 'subscriptionGuide'],
+    recommendedNext: ['goldenExample', 'evidencePatterns', 'schemaCatalog']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildGoldenExampleTopic(query) {
+  if (!query.exampleKey) {
+    throw validationError('exampleKey is required when topic=goldenExample');
+  }
+  const map = loadGoldenExamplesMap();
+  const doc = map[String(query.exampleKey)];
+  if (!doc) {
+    throw notFoundError(`Unknown exampleKey: ${query.exampleKey}`);
+  }
+  return buildHelpEnvelope({
+    topic: 'goldenExample',
+    key: String(query.exampleKey),
+    title: doc.title,
+    summary: doc.summary,
+    data: { example: doc },
+    related: ['goldenExamples', 'section'],
+    recommendedNext: ['section', 'workflow']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function loadEvidencePatternsDoc() {
+  if (evidenceCache) {
+    return evidenceCache;
+  }
+  evidenceCache = JSON.parse(fs.readFileSync(EVIDENCE_PATH, 'utf8'));
+  return evidenceCache;
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildEvidencePatternsTopic(query) {
+  const doc = loadEvidencePatternsDoc();
+  const patterns = (doc.patterns || [])
+    .filter((item) => matchesResourceRoleFilter(item, query))
+    .map((item) => ({
+      key: item.key,
+      title: item.title,
+      summary: item.summary,
+      role: item.role,
+      resourceType: item.resourceType,
+      relatedTopics: item.relatedTopics || []
+    }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+  return buildHelpEnvelope({
+    topic: 'evidencePatterns',
+    key: 'evidencePatterns',
+    title: 'Evidence patterns',
+    summary: 'Expected agent evidence steps for manifest editing workflows.',
+    data: { schemaVersion: doc.schemaVersion, patterns },
+    related: ['evidencePattern', 'workflow'],
+    recommendedNext: ['evidencePattern', 'goldenExamples']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildEvidencePatternTopic(query) {
+  if (!query.exampleKey) {
+    throw validationError('exampleKey is required when topic=evidencePattern');
+  }
+  const doc = loadEvidencePatternsDoc();
+  const pattern = (doc.patterns || []).find((item) => item.key === String(query.exampleKey));
+  if (!pattern) {
+    throw notFoundError(`Unknown evidence pattern key: ${query.exampleKey}`);
+  }
+  return buildHelpEnvelope({
+    topic: 'evidencePattern',
+    key: String(query.exampleKey),
+    title: pattern.title,
+    summary: pattern.summary,
+    data: { pattern },
+    related: ['evidencePatterns', 'workflow'],
+    recommendedNext: ['workflow', 'repairRules']
+  });
+}
+
+module.exports = {
+  buildGoldenExamplesTopic,
+  buildGoldenExampleTopic,
+  buildEvidencePatternsTopic,
+  buildEvidencePatternTopic
+};