@aifabrix/builder 2.49.2 → 2.51.0

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

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