@aifabrix/builder 2.53.1 → 2.55.0

package/lib/programmatic/channel-install-session.js

@@ -0,0 +1,218 @@
+/**
+ * Non-secret channel install session under the workspace integration folder.
+ *
+ * @fileoverview Persist help markdown + envelope for GET continue
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { ensureIntegrationDirectory } = require('./workspace-context');
+
+const SESSION_FILE = '.channel-install.json';
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function sessionPath(ctx) {
+  return path.join(ctx.getIntegrationPath(), SESSION_FILE);
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object} stored
+ */
+function writeSessionFile(filePath, stored) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(stored, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string|null}
+ */
+function instanceSessionPath(ctx) {
+  const instanceKey = typeof ctx.instanceSystemKey === 'string' ? ctx.instanceSystemKey.trim() : '';
+  if (!instanceKey || instanceKey === ctx.systemKey) {
+    return null;
+  }
+  return path.join(ctx.getIntegrationRoot(), instanceKey, SESSION_FILE);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object|null}
+ */
+function readChannelInstallSession(ctx) {
+  const filePath = sessionPath(ctx);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} session
+ * @returns {Object}
+ */
+function writeChannelInstallSession(ctx, session) {
+  ensureIntegrationDirectory(ctx);
+  const installationKey = ctx.instanceSystemKey || session.installationKey || ctx.systemKey;
+  const definitionKey = session.definitionKey || ctx.systemKey;
+  const stored = {
+    channelTarget: definitionKey,
+    definitionKey,
+    installationKey,
+    name: session.name,
+    displayName: session.displayName,
+    profile: session.profile || null,
+    allowExperimental: session.allowExperimental === true,
+    phase: session.phase,
+    helpMarkdown: session.helpMarkdown,
+    envelope: session.envelope,
+    slackAuthTicket: typeof session.slackAuthTicket === 'string' ? session.slackAuthTicket : undefined,
+    commandPrefix: trimSessionString(session.commandPrefix),
+    packageVersion: trimSessionString(session.packageVersion),
+    packageAppId: trimSessionString(session.packageAppId),
+    oauthPluginVaultReferenceId: trimSessionString(session.oauthPluginVaultReferenceId),
+    microsoftLoginUrl: trimSessionString(session.microsoftLoginUrl),
+    microsoftLoginUserCode: trimSessionString(session.microsoftLoginUserCode),
+    microsoftAuthConfigFallback: session.microsoftAuthConfigFallback === true ? true : undefined,
+    updatedAt: new Date().toISOString()
+  };
+  writeSessionFile(sessionPath(ctx), stored);
+  const extra = instanceSessionPath(ctx);
+  if (extra) {
+    writeSessionFile(extra, stored);
+  }
+  return stored;
+}
+
+/**
+ * @param {string} message
+ * @param {number} statusCode
+ * @returns {Error}
+ */
+function httpError(message, statusCode) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string|undefined}
+ */
+function trimSessionString(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    return undefined;
+  }
+  return value.trim();
+}
+
+/**
+ * @param {string} integrationRoot
+ * @param {string} folderName
+ * @returns {Object|null}
+ */
+function readNamedSession(integrationRoot, folderName) {
+  const filePath = path.join(integrationRoot, folderName, SESSION_FILE);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Object|null} session
+ * @param {string} definitionKey
+ * @returns {boolean}
+ */
+function sessionMatchesDefinition(session, definitionKey) {
+  if (!session) {
+    return false;
+  }
+  const key = session.definitionKey || session.channelTarget;
+  return key === definitionKey;
+}
+
+/**
+ * Catalog GET uses the definition key; the session lives on the instance folder.
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} definitionKey
+ * @returns {Object|null}
+ */
+function readChannelInstallSessionForDefinition(ctx, definitionKey) {
+  const direct = readChannelInstallSession(ctx);
+  if (sessionMatchesDefinition(direct, definitionKey)) {
+    return direct;
+  }
+  const root = typeof ctx.getIntegrationRoot === 'function' ? ctx.getIntegrationRoot() : '';
+  if (!root || !fs.existsSync(root)) {
+    return direct;
+  }
+  return newestMatchingSession(root, definitionKey, direct);
+}
+
+/**
+ * @param {string} root
+ * @param {string} definitionKey
+ * @param {Object|null} seed
+ * @returns {Object|null}
+ */
+function newestMatchingSession(root, definitionKey, seed) {
+  let best = seed;
+  let bestAt = (seed && seed.updatedAt) || '';
+  for (const name of fs.readdirSync(root)) {
+    if (name !== definitionKey && !String(name).startsWith(`${definitionKey}-`)) {
+      continue;
+    }
+    const session = readNamedSession(root, name);
+    if (!sessionMatchesDefinition(session, definitionKey)) {
+      continue;
+    }
+    const updated = session.updatedAt || '';
+    if (!best || updated >= bestAt) {
+      best = session;
+      bestAt = updated;
+    }
+  }
+  return best;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object}
+ */
+function requireChannelInstallSession(ctx) {
+  const session = readChannelInstallSession(ctx);
+  if (!session) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  return session;
+}
+
+module.exports = {
+  SESSION_FILE,
+  sessionPath,
+  readChannelInstallSession,
+  readChannelInstallSessionForDefinition,
+  writeChannelInstallSession,
+  requireChannelInstallSession,
+  httpError
+};

package/lib/programmatic/help-content/channel-onboarding.md

@@ -18,6 +18,8 @@ Complete validate and upload for the target systemKey so the dataplane exposes M
 | slack | Slack workspace assistant |
 | microsoft-copilot | Microsoft Copilot package (runtime-orchestration MCP) |
 | chatgpt | ChatGPT custom MCP app (runtime-orchestration) |
+| claude | Claude custom connector (runtime-orchestration) |
+| mcp-client | Developer MCP client (Cursor, VS Code, Copilot IDE profile) |
 | web-embed | Experimental embedded web assistant |
 
 Each target requires credentials and deploy approval. Read topic connectedSystemUi after upload for dataplane handoff paths.

package/lib/programmatic/help-content/cip-overview.md

@@ -10,7 +10,9 @@ Every operation contains an ordered steps array. Each step is a single keyed obj
 
 ## Common step patterns
 
-Fetch resolves data from OpenAPI references, raw HTTP, or another datasource. Map applies fieldMappings to normalize vendor payloads. Filter applies optional ABAC or JMESPath expressions. Output emits records for sync and storage.
+Fetch resolves data from OpenAPI references, raw HTTP, another datasource, a viewpoint SQL query, or local record storage. Map applies fieldMappings to normalize vendor payloads. Filter applies optional ABAC or JMESPath expressions. Output emits records for sync and storage.
+
+`fetch.source` is a closed enum: `openapi`, `http`, `datasource`, `viewpoint`, `record`. The fetch token `record` is singular; `output.mode` stays plural `records`. Persist vs read on `record` follows operation `shape` (`create` or `update`), not the capability key. CIP `fetch.source` compiles to COM `source`.
 
 Paginate handles cursor, page, or offset strategies for list operations. Python inline runs sandboxed transforms when declarative steps are insufficient.
 

package/lib/programmatic/http-raw-response.js

@@ -0,0 +1,62 @@
+/**
+ * Raw HTTP outcomes for builder-api (markdown / ZIP bytes).
+ *
+ * @fileoverview Bypass JSON envelope for help.md and artifact downloads
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} params
+ * @param {string} params.contentType
+ * @param {string|Buffer} params.body
+ * @param {string} [params.fileName]
+ * @returns {{ __httpRaw: true, contentType: string, body: string|Buffer, fileName?: string }}
+ */
+function createHttpRawResult(params) {
+  const result = {
+    __httpRaw: true,
+    contentType: params.contentType,
+    body: params.body
+  };
+  if (params.fileName) {
+    result.fileName = params.fileName;
+  }
+  return result;
+}
+
+/**
+ * @param {unknown} result
+ * @returns {boolean}
+ */
+function isHttpRawResult(result) {
+  return Boolean(result && typeof result === 'object' && result.__httpRaw === true);
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {Object} raw
+ * @param {string} [requestId]
+ * @returns {void}
+ */
+function sendRaw(res, raw, requestId) {
+  const headers = {
+    'Content-Type': raw.contentType || 'application/octet-stream'
+  };
+  if (requestId) {
+    headers['X-Request-Id'] = requestId;
+  }
+  if (raw.fileName) {
+    headers['Content-Disposition'] = `attachment; filename="${raw.fileName}"`;
+  }
+  res.writeHead(200, headers);
+  res.end(raw.body);
+}
+
+module.exports = {
+  createHttpRawResult,
+  isHttpRawResult,
+  sendRaw
+};

package/lib/programmatic/index.js

@@ -7,6 +7,7 @@
 const workspaceContext = require('./workspace-context');
 const runUpload = require('./run-upload');
 const runDeploy = require('./run-deploy');
+const runDownload = require('./run-download');
 const runProtection = require('./run-protection');
 const runWizard = require('./run-wizard');
 const runRepair = require('./run-repair');
@@ -32,6 +33,7 @@ module.exports = {
   ...workspaceContext,
   ...runUpload,
   ...runDeploy,
+  ...runDownload,
   ...runProtection,
   ...runWizard,
   ...runRepair,

package/lib/programmatic/openapi-apply-result-schemas.js

@@ -21,6 +21,14 @@ const OPENAPI_APPLY_RESULT_SCHEMAS = {
     },
     ['deployed']
   ),
+  DownloadResultData: frozenObject(
+    {
+      downloaded: { type: 'boolean' },
+      dryRun: { type: 'boolean' },
+      systemKey: schemaRef('SystemKey')
+    },
+    ['downloaded', 'dryRun', 'systemKey']
+  ),
   ProtectionUploadData: frozenObject(
     {
       datasourceKey: schemaRef('DatasourceKey'),

package/lib/programmatic/openapi-channel-install-bindings.js

@@ -0,0 +1,179 @@
+/**
+ * OpenAPI operation bindings for generic channel install routes.
+ *
+ * @fileoverview Keep openapi-operation-bindings.js under the line limit
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYSTEM_KEY_PARAM = {
+  name: 'systemKey',
+  in: 'path',
+  required: true,
+  schema: { $ref: '#/components/schemas/SystemKey' },
+  description: 'Channel target key (slack, chatgpt, claude, microsoft-copilot, teams-bot, web-embed, mcp-client).'
+};
+
+const ARTIFACT_ID_PARAM = {
+  name: 'artifactId',
+  in: 'path',
+  required: true,
+  schema: { type: 'string' },
+  description: 'Artifact id from the help document download link (for example appPackage).'
+};
+
+const PROVIDER_PARAM = {
+  name: 'provider',
+  in: 'path',
+  required: true,
+  schema: { type: 'string' },
+  description: 'Vendor callback provider key (opaque; used only to resume install).'
+};
+
+/**
+ * @param {string} schemaName
+ * @param {boolean} [required]
+ * @returns {Object}
+ */
+function jsonRequestBody(schemaName, required = false) {
+  return {
+    required,
+    content: {
+      'application/json': {
+        schema: { $ref: `#/components/schemas/${schemaName}` }
+      }
+    }
+  };
+}
+
+/** @type {Record<string, Object>} */
+const CHANNEL_INSTALL_BINDINGS = {
+  listChannelTargets: {
+    queryParameters: [
+      {
+        name: 'allowExperimental',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'When true, include experimental channel targets such as web-embed.'
+      }
+    ],
+    successResponse: 'ListChannelTargetsResponse'
+  },
+  getChannelDefinitionDetail: {
+    parameters: [
+      {
+        name: 'definitionKey',
+        in: 'path',
+        required: true,
+        schema: { $ref: '#/components/schemas/SystemKey' },
+        description: 'Channel definition key (catalog identity, not the Connected System instance key).'
+      }
+    ],
+    successResponse: 'ChannelDefinitionDetailResponse'
+  },
+  getChannelInstallation: {
+    parameters: [
+      {
+        name: 'definitionKey',
+        in: 'path',
+        required: true,
+        schema: { $ref: '#/components/schemas/SystemKey' },
+        description: 'Channel definition key.'
+      },
+      {
+        name: 'systemKey',
+        in: 'path',
+        required: true,
+        schema: { $ref: '#/components/schemas/SystemKey' },
+        description: 'Connected System instance key for this installation.'
+      }
+    ],
+    successResponse: 'ChannelInstallationDetailResponse'
+  },
+  runChannelInstall: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelInstallRequest', true),
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  getChannelInstall: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'verbose',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'When true, return the full machine envelope (remainingSteps, useValues). Default JSON already includes phase and userActions.'
+      }
+    ],
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  getChannelInstallHelp: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelInstallHelpResponse',
+    extraSuccessContent: {
+      'text/markdown': {
+        schema: { type: 'string', description: 'Help document body (same remaining steps as INSTALL.md).' }
+      }
+    }
+  },
+  continueChannelInstall: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelInstallContinueRequest'),
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  listChannelArtifacts: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ListChannelArtifactsResponse'
+  },
+  getChannelArtifact: {
+    parameters: [SYSTEM_KEY_PARAM, ARTIFACT_ID_PARAM],
+    successResponse: 'ChannelArtifactBytesResponse',
+    extraSuccessContent: {
+      'application/zip': {
+        schema: { type: 'string', format: 'binary', description: 'Package ZIP bytes.' }
+      }
+    }
+  },
+  getChannelCallback: {
+    parameters: [SYSTEM_KEY_PARAM, PROVIDER_PARAM],
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  postChannelCallback: {
+    parameters: [SYSTEM_KEY_PARAM, PROVIDER_PARAM],
+    requestBody: jsonRequestBody('EmptyRequestBody'),
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  buildChannelPackage: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelPackageRequest'),
+    successResponse: 'ChannelPackageResponse'
+  },
+  getChannelPackageSummary: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelPackageSummaryResponse'
+  },
+  getChannelPackageZip: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelPackageZipResponse'
+  },
+  getChannelBranding: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelBrandingResponse'
+  },
+  patchChannelBranding: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelBrandingPatchRequest'),
+    successResponse: 'ChannelBrandingResponse'
+  },
+  getAuthPermissions: {
+    successResponse: 'AuthPermissionsResponse'
+  }
+};
+
+module.exports = {
+  CHANNEL_INSTALL_BINDINGS
+};