@aifabrix/builder 2.49.2 → 2.50.0

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

@@ -0,0 +1,172 @@
+/**
+ * Governance help topics for builder-api LLM bootstrap (plan 154.7).
+ *
+ * @fileoverview Platform roles, resource types, dimensions, channel onboarding
+ * @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 { listPlatformRoles } = require('./platform-rbac-catalog');
+const { CHANNEL_TARGET_KEYS, CHANNEL_TARGETS } = require('../channels/channel-targets');
+
+const BUILDER_HELP_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help');
+const HELP_MD_DIR = path.join(__dirname, 'help-content');
+
+/**
+ * @param {string} fileName
+ * @returns {{ bodyText: string, sections: Array<{ title: string, body: string }> }}
+ */
+function parseMarkdownHelpFile(fileName) {
+  const raw = fs.readFileSync(path.join(HELP_MD_DIR, fileName), 'utf8');
+  let bodyText = raw.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+  bodyText = bodyText.replace(/https?:\/\/\S+/g, '');
+  const sections = [];
+  const lines = bodyText.split('\n');
+  let current = null;
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      if (current) sections.push(current);
+      current = { title: line.slice(3).trim(), body: '' };
+      continue;
+    }
+    if (current) current.body += `${line}\n`;
+  }
+  if (current) sections.push(current);
+  for (const s of sections) s.body = s.body.trim();
+  return { bodyText: bodyText.trim(), sections };
+}
+
+/**
+ * @returns {Object}
+ */
+function loadPlatformRolesFixture() {
+  return JSON.parse(fs.readFileSync(path.join(BUILDER_HELP_DIR, 'platform-roles.json'), 'utf8'));
+}
+
+/**
+ * @returns {Object}
+ */
+function loadResourceTypeCatalog() {
+  return JSON.parse(fs.readFileSync(path.join(BUILDER_HELP_DIR, 'resource-type-catalog.json'), 'utf8'));
+}
+
+/**
+ * @returns {Object}
+ */
+function buildPlatformRolesTopic() {
+  const fixture = loadPlatformRolesFixture();
+  return buildHelpEnvelope({
+    topic: 'platformRoles',
+    key: 'platformRoles',
+    title: 'Platform RBAC roles',
+    summary:
+      'Eight platform roles shared with dataplane rbac.yaml. Use rbacPreset platform for facade APIs instead of per-system admin/reader.',
+    data: {
+      roles: listPlatformRoles(),
+      permissionMatrix: fixture.permissionMatrix || [],
+      rbacPreset: 'platform',
+      forbiddenPatterns: ['{systemKey}-admin', '{systemKey}-reader']
+    },
+    related: ['workflow', 'repairRules', 'section', 'resourceTypeCatalog'],
+    recommendedNext: ['topic=section&sectionKey=system.rolesPermissions', 'topic=resourceTypeCatalog']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildResourceTypeCatalogTopic(query) {
+  const catalog = loadResourceTypeCatalog();
+  let rows = catalog.resourceTypes || [];
+  if (query.category) {
+    rows = rows.filter((r) => r.category === query.category);
+  }
+  if (query.resourceType) {
+    rows = rows.filter((r) => r.key === query.resourceType);
+  }
+  return buildHelpEnvelope({
+    topic: 'resourceTypeCatalog',
+    key: query.category || query.resourceType || 'all',
+    title: 'Resource type catalog',
+    summary:
+      'Taxonomy-only catalog keys for datasource.resourceType. Challenge generic document when a business token fits.',
+    data: {
+      schemaVersion: catalog.schemaVersion,
+      minimumSystemKeys: catalog.minimumSystemKeys,
+      resourceTypes: rows,
+      orchestrationRecommendation: {
+        entityType: 'none',
+        suggestedResourceType: 'workspace',
+        rationale: 'Facade orchestration APIs that expose workspace manifest operations'
+      }
+    },
+    related: ['schemaCatalog', 'dimensionsGuide', 'goldenExamples'],
+    recommendedNext: ['topic=section&sectionKey=datasource.resourceType']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function buildDimensionsGuideTopic() {
+  const parsed = parseMarkdownHelpFile('dimensions-guide.md');
+  return buildHelpEnvelope({
+    topic: 'dimensionsGuide',
+    key: 'dimensionsGuide',
+    title: 'Dimensions and ABAC grounding',
+    summary: 'When and how to declare dimensions; challenge missing governance attributes before protection.',
+    data: {
+      bodyText: parsed.bodyText,
+      sections: parsed.sections,
+      appliesToEntityTypes: ['recordStorage', 'documentStorage', 'serviceContract'],
+      forbiddenOnEntityTypes: ['none']
+    },
+    related: ['evidencePatterns', 'section', 'subscriptionGuide'],
+    recommendedNext: ['topic=section&sectionKey=datasource.dimensions', 'topic=evidencePattern&exampleKey=protection-dimension-gate']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function buildChannelOnboardingTopic() {
+  const parsed = parseMarkdownHelpFile('channel-onboarding.md');
+  const targets = CHANNEL_TARGET_KEYS.map((key) => {
+    const t = CHANNEL_TARGETS[key];
+    return {
+      key: t.key,
+      channelType: t.channelType,
+      capabilities: [...t.capabilities],
+      approvalRequired: t.approvalRequired,
+      experimental: t.experimental
+    };
+  });
+  return buildHelpEnvelope({
+    topic: 'channelOnboarding',
+    key: 'channelOnboarding',
+    title: 'Channel onboarding from work list',
+    summary: 'Publish external system from workspace work list, then scaffold assistant channel target.',
+    data: {
+      bodyText: parsed.bodyText,
+      sections: parsed.sections,
+      workListRoute: 'GET /workspaces/me/systems',
+      channelTargets: targets,
+      cliSteps: ['channel scaffold <target>', 'channel add <target>']
+    },
+    related: ['workflow', 'connectedSystemUi', 'platformRoles'],
+    recommendedNext: ['topic=workflow', 'topic=connectedSystemUi']
+  });
+}
+
+module.exports = {
+  buildPlatformRolesTopic,
+  buildResourceTypeCatalogTopic,
+  buildDimensionsGuideTopic,
+  buildChannelOnboardingTopic
+};

package/lib/programmatic/builder-help-schema-catalog.js

@@ -0,0 +1,92 @@
+/**
+ * Schema catalog index for builder-api LLM help (plan 154.6).
+ *
+ * @fileoverview Top-level properties and $defs keys — not full JSON Schema payloads
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_DIR = path.join(__dirname, '..', 'schema');
+
+/** @type {Record<string, Object>|null} */
+const catalogCache = {};
+
+/**
+ * @param {Object} propSchema
+ * @returns {string|undefined}
+ */
+function summarizeProperty(propSchema) {
+  if (!propSchema || typeof propSchema !== 'object') {
+    return undefined;
+  }
+  if (typeof propSchema.description === 'string') {
+    return propSchema.description.split('\n')[0].trim();
+  }
+  if (propSchema.$ref) {
+    return `Ref ${String(propSchema.$ref).split('/').pop()}`;
+  }
+  return undefined;
+}
+
+/**
+ * @param {'system' | 'datasource'} target
+ * @returns {Object}
+ */
+function loadSchemaDoc(target) {
+  const fileName = target === 'system' ? 'external-system.schema.json' : 'external-datasource.schema.json';
+  return JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, fileName), 'utf8'));
+}
+
+/**
+ * @param {'system' | 'datasource'} target
+ * @returns {Object}
+ */
+function buildSchemaCatalogForTarget(target) {
+  if (catalogCache[target]) {
+    return catalogCache[target];
+  }
+  const doc = loadSchemaDoc(target);
+  const requiredSet = new Set(doc.required || []);
+  const rootProperties = Object.keys(doc.properties || {})
+    .sort()
+    .map((name) => ({
+      name,
+      required: requiredSet.has(name),
+      summary: summarizeProperty(doc.properties[name])
+    }));
+  const defKeys = Object.keys(doc.$defs || {}).sort();
+  const catalog = {
+    target,
+    schemaId: doc.$id || doc.metadata?.key,
+    schemaVersion: doc.metadata?.version,
+    rootPropertyCount: rootProperties.length,
+    rootProperties,
+    defKeys
+  };
+  catalogCache[target] = catalog;
+  return catalog;
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSchemaCatalogTopicData(query) {
+  const filter = query.resourceType === 'system' || query.resourceType === 'datasource' ? query.resourceType : null;
+  if (filter) {
+    return { catalogs: [buildSchemaCatalogForTarget(filter)] };
+  }
+  return {
+    catalogs: [buildSchemaCatalogForTarget('system'), buildSchemaCatalogForTarget('datasource')]
+  };
+}
+
+module.exports = {
+  buildSchemaCatalogForTarget,
+  buildSchemaCatalogTopicData
+};

package/lib/programmatic/builder-help.js

@@ -0,0 +1,361 @@
+/**
+ * Builder API LLM help topic dispatch (plan 154.5, 154.6).
+ *
+ * @fileoverview Read-only help envelope from MD, fixtures, and 154.4 registries
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { listSectionKeys, getSectionDefinition, buildSchemaFragment } = require('./manifest-section-registry');
+const { SECTION_EDGES, SECTION_REPAIR_HOOKS, getDownstream } = require('./manifest-section-dependency-graph');
+const { HOOK_FLAG_MAP } = require('./manifest-repair');
+const { buildSchemaCatalogTopicData } = require('./builder-help-schema-catalog');
+const {
+  HELP_CONTENT_VERSION,
+  HELP_SCHEMA_VERSION,
+  buildHelpEnvelope
+} = require('./builder-help-envelope');
+const {
+  buildGoldenExamplesTopic,
+  buildGoldenExampleTopic,
+  buildEvidencePatternsTopic,
+  buildEvidencePatternTopic
+} = require('./builder-help-fixtures');
+const { buildConnectedSystemUiTopic } = require('./builder-help-connected-system-ui');
+const { buildEnterpriseSyncFabrixTopic } = require('./builder-help-enterprise-sync-fabrix');
+const {
+  buildPlatformRolesTopic,
+  buildResourceTypeCatalogTopic,
+  buildDimensionsGuideTopic,
+  buildChannelOnboardingTopic
+} = require('./builder-help-governance');
+
+const HELP_TOPICS = Object.freeze([
+  'overview',
+  'sections',
+  'section',
+  'dependencyGraph',
+  'repairRules',
+  'workflow',
+  'schemaCatalog',
+  'subscriptionGuide',
+  'cipOverview',
+  'goldenExamples',
+  'goldenExample',
+  'evidencePatterns',
+  'evidencePattern',
+  'connectedSystemUi',
+  'enterpriseSyncFabrix',
+  'platformRoles',
+  'resourceTypeCatalog',
+  'dimensionsGuide',
+  'channelOnboarding'
+]);
+
+/** @type {Readonly<Record<string, string>>} */
+const PROSE_TOPIC_FILES = Object.freeze({
+  overview: 'overview.md',
+  workflow: 'workflow.md',
+  subscriptionGuide: 'subscription-guide.md',
+  cipOverview: 'cip-overview.md',
+  enterpriseSyncFabrix: 'enterprise-sync-fabrix.md'
+});
+
+const HELP_MD_DIR = path.join(__dirname, 'help-content');
+
+/**
+ * @param {string} message
+ * @returns {Error}
+ */
+function validationError(message) {
+  const err = new Error(message);
+  err.statusCode = 400;
+  return err;
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripLinksFromText(text) {
+  let out = String(text || '');
+  out = out.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+  out = out.replace(/https?:\/\/[^\s)]+/gi, '');
+  return out.replace(/\s{2,}/g, ' ').trim();
+}
+
+/**
+ * @param {string} heading
+ * @param {string[]} bodyLines
+ * @returns {{ heading: string, body: string }}
+ */
+function flushMarkdownSection(heading, bodyLines) {
+  return { heading, body: stripLinksFromText(bodyLines.join('\n')) };
+}
+
+/**
+ * @param {string} fileName
+ * @returns {{ title: string, summary: string, sections: Object[], bodyText: string }}
+ */
+function parseMarkdownHelpFile(fileName) {
+  const raw = fs.readFileSync(path.join(HELP_MD_DIR, fileName), 'utf8');
+  let title = '';
+  let summary = '';
+  /** @type {Object[]} */
+  const sections = [];
+  let currentHeading = '';
+  /** @type {string[]} */
+  let currentBody = [];
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (line.startsWith('# ')) {
+      title = stripLinksFromText(line.slice(2));
+    } else if (line.startsWith('## ')) {
+      if (currentHeading) {
+        sections.push(flushMarkdownSection(currentHeading, currentBody));
+      }
+      currentHeading = stripLinksFromText(line.slice(3));
+      currentBody = [];
+    } else {
+      if (!summary && line.trim()) {
+        summary = stripLinksFromText(line);
+      }
+      if (currentHeading) {
+        currentBody.push(line);
+      }
+    }
+  }
+  if (currentHeading) {
+    sections.push(flushMarkdownSection(currentHeading, currentBody));
+  }
+  return { title, summary, sections, bodyText: stripLinksFromText(raw) };
+}
+
+/**
+ * @param {string} topic
+ * @returns {Object}
+ */
+function buildProseTopic(topic) {
+  const fileName = PROSE_TOPIC_FILES[topic];
+  if (!fileName) {
+    throw validationError(`Unknown prose topic: ${topic}`);
+  }
+  const parsed = parseMarkdownHelpFile(fileName);
+  const recommendedNextByTopic = {
+    overview: ['workflow', 'schemaCatalog'],
+    workflow: ['sections', 'connectedSystemUi', 'enterpriseSyncFabrix'],
+    subscriptionGuide: ['section', 'goldenExamples'],
+    cipOverview: ['schemaCatalog', 'section']
+  };
+  const relatedByTopic = {
+    overview: ['workflow', 'sections', 'schemaCatalog'],
+    workflow: ['overview', 'section', 'connectedSystemUi'],
+    subscriptionGuide: ['section', 'goldenExamples', 'evidencePatterns'],
+    cipOverview: ['schemaCatalog', 'section', 'workflow']
+  };
+  return buildHelpEnvelope({
+    topic,
+    key: topic,
+    title: parsed.title,
+    summary: parsed.summary,
+    data: { sections: parsed.sections, bodyText: parsed.bodyText },
+    related: relatedByTopic[topic] || [],
+    recommendedNext: recommendedNextByTopic[topic] || ['sections']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSchemaCatalogTopic(query) {
+  return buildHelpEnvelope({
+    topic: 'schemaCatalog',
+    key: query.resourceType === 'system' || query.resourceType === 'datasource' ? query.resourceType : 'schemaCatalog',
+    title: 'Manifest schema catalog',
+    summary: 'Top-level schema properties and definition keys — use section topic for fragments and validate for errors.',
+    data: buildSchemaCatalogTopicData(query),
+    related: ['section', 'cipOverview'],
+    recommendedNext: ['section', 'cipOverview']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSectionsTopic(query) {
+  const targetFilter =
+    query.resourceType === 'system' || query.resourceType === 'datasource' ? query.resourceType : undefined;
+  const sectionKeys = listSectionKeys(targetFilter)
+    .sort()
+    .map((sectionKey) => {
+      const def = getSectionDefinition(sectionKey);
+      return {
+        sectionKey,
+        target: def.target,
+        mutable: def.mutable,
+        required: def.required,
+        sourceOfTruth: def.sourceOfTruth,
+        blocked: def.blocked === true,
+        repairHooks: [...(def.repairHooks || [])].sort()
+      };
+    });
+  return buildHelpEnvelope({
+    topic: 'sections',
+    key: 'sections',
+    title: 'Manifest sections',
+    summary: 'Governed section keys for external system and datasource manifests.',
+    data: { sectionKeys },
+    related: ['section', 'dependencyGraph', 'repairRules'],
+    recommendedNext: ['workflow', 'section']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildSectionTopic(query) {
+  if (!query.sectionKey) {
+    throw validationError('sectionKey is required when topic=section');
+  }
+  const def = getSectionDefinition(String(query.sectionKey));
+  const downstream = getDownstream(String(query.sectionKey)).sort();
+  return buildHelpEnvelope({
+    topic: 'section',
+    key: String(query.sectionKey),
+    title: `Section ${query.sectionKey}`,
+    summary: `Governed manifest section ${query.sectionKey} (${def.target}).`,
+    data: {
+      definition: {
+        target: def.target,
+        paths: def.paths,
+        mutable: def.mutable,
+        required: def.required,
+        sourceOfTruth: def.sourceOfTruth,
+        blocked: def.blocked === true,
+        repairHooks: [...(def.repairHooks || [])].sort()
+      },
+      schemaFragment: buildSchemaFragment(def.target, def.paths[0]),
+      downstreamSectionKeys: downstream
+    },
+    related: downstream.slice(0, 3),
+    recommendedNext: ['dependencyGraph', 'repairRules', 'workflow']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function buildDependencyGraphTopic() {
+  const edges = SECTION_EDGES.map(([from, to]) => ({ from, to })).sort((a, b) =>
+    `${a.from}:${a.to}`.localeCompare(`${b.from}:${b.to}`)
+  );
+  const nodeSet = new Set();
+  for (const edge of edges) {
+    nodeSet.add(edge.from);
+    nodeSet.add(edge.to);
+  }
+  return buildHelpEnvelope({
+    topic: 'dependencyGraph',
+    key: 'dependencyGraph',
+    title: 'Section dependency graph',
+    summary: 'Directed edges from source sections to dependent sections for repair traversal.',
+    data: { edges, nodes: [...nodeSet].sort() },
+    related: ['repairRules', 'sections'],
+    recommendedNext: ['repairRules', 'sections']
+  });
+}
+
+/**
+ * @returns {Object}
+ */
+function buildRepairRulesTopic() {
+  const hooks = Object.keys(HOOK_FLAG_MAP).sort();
+  return buildHelpEnvelope({
+    topic: 'repairRules',
+    key: 'repairRules',
+    title: 'Manifest repair rules',
+    summary: 'Named repair hooks and section-to-hook mappings used after section patches.',
+    data: {
+      hooks,
+      hookFlags: hooks.map((hook) => ({ hook, repairFlag: HOOK_FLAG_MAP[hook] })),
+      sectionHooks: Object.keys(SECTION_REPAIR_HOOKS)
+        .sort()
+        .map((sectionKey) => ({
+          sectionKey,
+          hooks: [...SECTION_REPAIR_HOOKS[sectionKey]].sort()
+        }))
+    },
+    related: ['dependencyGraph', 'section'],
+    recommendedNext: ['workflow', 'dependencyGraph']
+  });
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function getBuilderHelp(query = {}) {
+  const topic = query.topic;
+  if (!topic) {
+    throw validationError('topic query parameter is required');
+  }
+  if (!HELP_TOPICS.includes(topic)) {
+    throw validationError(`Unknown topic: ${topic}`);
+  }
+
+  /** @type {Record<string, (q: Object) => Object>} */
+  const handlers = {
+    overview: () => buildProseTopic('overview'),
+    workflow: () => buildProseTopic('workflow'),
+    subscriptionGuide: () => buildProseTopic('subscriptionGuide'),
+    cipOverview: () => buildProseTopic('cipOverview'),
+    schemaCatalog: buildSchemaCatalogTopic,
+    sections: buildSectionsTopic,
+    section: buildSectionTopic,
+    dependencyGraph: () => buildDependencyGraphTopic(),
+    repairRules: () => buildRepairRulesTopic(),
+    goldenExamples: buildGoldenExamplesTopic,
+    goldenExample: buildGoldenExampleTopic,
+    evidencePatterns: buildEvidencePatternsTopic,
+    evidencePattern: buildEvidencePatternTopic,
+    connectedSystemUi: (q) => {
+      const envelope = buildConnectedSystemUiTopic(q);
+      const parsed = parseMarkdownHelpFile('connected-system-ui.md');
+      envelope.data.bodyText = parsed.bodyText;
+      envelope.data.sections = parsed.sections;
+      return envelope;
+    },
+    enterpriseSyncFabrix: (q) => buildEnterpriseSyncFabrixTopic(q),
+    platformRoles: () => buildPlatformRolesTopic(),
+    resourceTypeCatalog: buildResourceTypeCatalogTopic,
+    dimensionsGuide: () => buildDimensionsGuideTopic(),
+    channelOnboarding: () => buildChannelOnboardingTopic()
+  };
+
+  return handlers[topic](query);
+}
+
+/**
+ * @param {Object} query - Help query parameters (topic, sectionKey, exampleKey, filters).
+ * @returns {Object} Help envelope payload returned inside the builder-api success data field.
+ */
+function handleGetBuilderHelp(query) {
+  return getBuilderHelp(query);
+}
+
+module.exports = {
+  HELP_TOPICS,
+  HELP_CONTENT_VERSION,
+  HELP_SCHEMA_VERSION,
+  stripLinksFromText,
+  buildHelpEnvelope,
+  getBuilderHelp,
+  handleGetBuilderHelp
+};