@aifabrix/builder 2.53.1 → 2.55.0

package/lib/channels/channel-install-profiles.js

@@ -0,0 +1,90 @@
+/**
+ * Generic channel install profiles (optional `profile` on the same POST).
+ *
+ * @fileoverview Catalog profiles from CHANNEL_TARGETS or mcp-client templates
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { CHANNEL_TARGETS } = require('./channel-targets');
+const { listMcpClientProfileChoices } = require('./mcp-client/profiles');
+
+/**
+ * @param {{ key?: string, displayLabel?: string, name?: string, value?: string }} row
+ * @returns {{ key: string, displayLabel: string }}
+ */
+function toProfileRow(row) {
+  return {
+    key: row.key || row.value,
+    displayLabel: row.displayLabel || row.name || row.key || row.value
+  };
+}
+
+/**
+ * @returns {{ key: string, displayLabel: string }[]}
+ */
+function mcpClientProfiles() {
+  try {
+    return listMcpClientProfileChoices().map(toProfileRow);
+  } catch {
+    return [
+      { key: 'cursor', displayLabel: 'Cursor' },
+      { key: 'vscode', displayLabel: 'VS Code' },
+      { key: 'github-copilot', displayLabel: 'GitHub Copilot' }
+    ];
+  }
+}
+
+/**
+ * Profiles accepted on POST install.
+ * @param {string} channelKey
+ * @returns {{ key: string, displayLabel: string }[]}
+ */
+function profilesForInstall(channelKey) {
+  const target = CHANNEL_TARGETS[channelKey];
+  if (target && Array.isArray(target.profiles) && target.profiles.length > 0) {
+    return target.profiles.map(toProfileRow);
+  }
+  if (channelKey === 'mcp-client') {
+    return mcpClientProfiles();
+  }
+  return [];
+}
+
+/**
+ * Profiles advertised on GET /channels when the target is live.
+ * @param {string} channelKey
+ * @returns {{ key: string, displayLabel: string }[]}
+ */
+function profilesForCatalogRow(channelKey) {
+  if (!CHANNEL_TARGETS[channelKey]) {
+    return [];
+  }
+  return profilesForInstall(channelKey);
+}
+
+/**
+ * @param {string} channelKey
+ * @returns {boolean}
+ */
+function installRequiresProfile(channelKey) {
+  return profilesForInstall(channelKey).length > 0;
+}
+
+/**
+ * @param {string} channelKey
+ * @param {string} profile
+ * @returns {boolean}
+ */
+function isAllowedInstallProfile(channelKey, profile) {
+  return profilesForInstall(channelKey).some((row) => row.key === profile);
+}
+
+module.exports = {
+  profilesForCatalogRow,
+  profilesForInstall,
+  installRequiresProfile,
+  isAllowedInstallProfile
+};

package/lib/channels/channel-instance-collision.js

@@ -0,0 +1,118 @@
+/**
+ * HTTP install collision: instance key already on Dataplane → 409.
+ *
+ * @fileoverview Existing instance becomes continue/update; CLI skip stays on add-channel
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getExternalSystem } = require('../api/external-systems.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+const { httpError } = require('../programmatic/channel-install-session');
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isNotFoundError(err) {
+  const status = Number(
+    err && (err.statusCode || err.status || (err.errorData && err.errorData.status))
+  );
+  return status === 404;
+}
+
+/**
+ * True only when Dataplane returned that Connected System key.
+ * Envelopes, RFC 7807 bodies, leftover catalog keys, and empty objects are not collisions.
+ *
+ * @param {unknown} system
+ * @param {string} instanceKey
+ * @returns {boolean}
+ */
+function isExistingChannelInstance(system, instanceKey) {
+  if (!system || typeof system !== 'object' || Array.isArray(system)) {
+    return false;
+  }
+  const status = Number(system.status || system.statusCode);
+  if (status === 404) {
+    return false;
+  }
+  const key =
+    (typeof system.key === 'string' && system.key) ||
+    (typeof system.systemKey === 'string' && system.systemKey) ||
+    null;
+  return key === instanceKey;
+}
+
+/**
+ * @param {Object} ctx
+ * @param {string} [instanceKey]
+ * @param {Object} [deps]
+ * @returns {Promise<void>}
+ */
+async function assertChannelInstanceAvailable(ctx, instanceKey, deps = {}) {
+  if (!instanceKey || deps.continueInstall === true || deps.force === true) {
+    return;
+  }
+  const getSystem = deps.getExternalSystem || getExternalSystem;
+  let system = null;
+  try {
+    const res = await getSystem(ctx.dataplaneUrl, instanceKey, {
+      type: 'bearer',
+      token: ctx.bearerToken,
+      preserveBearer: true
+    });
+    system = unwrapApiData(res);
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      return;
+    }
+    throw err;
+  }
+  if (!isExistingChannelInstance(system, instanceKey)) {
+    return;
+  }
+  const displayName = typeof system.displayName === 'string' ? system.displayName.trim() : '';
+  const named = displayName && displayName !== instanceKey ? ` ("${displayName}")` : '';
+  throw httpError(`Channel instance "${instanceKey}"${named} already exists.`, 409);
+}
+
+/**
+ * Same Connected System key is an in-place update, not a 409.
+ * @param {Object} ctx
+ * @param {Object} addOptions
+ * @param {Object} [body]
+ * @param {Object} [deps]
+ * @returns {Promise<void>}
+ */
+async function adoptExistingInstanceAsContinue(ctx, addOptions, body, deps = {}) {
+  if (addOptions.continueInstall === true || addOptions.force === true) {
+    return;
+  }
+  if (body && (body.continueInstall === true || body.force === true)) {
+    addOptions.continueInstall = true;
+    return;
+  }
+  try {
+    await assertChannelInstanceAvailable(ctx, addOptions.systemKey, {
+      getExternalSystem: deps.getExternalSystem
+    });
+  } catch (err) {
+    if (Number(err.statusCode) !== 409) {
+      throw err;
+    }
+    addOptions.continueInstall = true;
+    if (body && typeof body === 'object') {
+      body.continueInstall = true;
+    }
+  }
+}
+
+module.exports = {
+  assertChannelInstanceAvailable,
+  adoptExistingInstanceAsContinue,
+  isExistingChannelInstance,
+  isNotFoundError
+};

package/lib/channels/channel-instance-key.js

@@ -0,0 +1,100 @@
+/**
+ * Derive and validate Connected System instance keys for channel install.
+ *
+ * @fileoverview definition key ≠ instance key
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const INSTANCE_KEY_RE = /^[a-z0-9-]+$/;
+const MAX_KEY_LENGTH = 40;
+const INSTANCE_EQUALS_CATALOG =
+  'Connected System key cannot equal the catalog key.';
+
+/**
+ * @param {string} definitionKey
+ * @param {string} instanceKey
+ * @returns {void}
+ */
+function assertInstanceKeyNotCatalogKey(definitionKey, instanceKey) {
+  if (String(instanceKey) === String(definitionKey)) {
+    throw new Error(
+      `${INSTANCE_EQUALS_CATALOG} Use ${definitionKey}-<name-slug>, not "${definitionKey}".`
+    );
+  }
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function slugDisplayName(name) {
+  return String(name || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function clipInstanceKey(key) {
+  if (key.length <= MAX_KEY_LENGTH) {
+    return key;
+  }
+  return key.slice(0, MAX_KEY_LENGTH).replace(/-+$/g, '');
+}
+
+/**
+ * @param {string} definitionKey
+ * @param {string} name
+ * @param {string} [explicitKey]
+ * @returns {string}
+ */
+function deriveChannelInstanceKey(definitionKey, name, explicitKey) {
+  let instanceKey;
+  if (typeof explicitKey === 'string' && explicitKey.trim()) {
+    const trimmed = explicitKey.trim().toLowerCase();
+    if (!INSTANCE_KEY_RE.test(trimmed) || trimmed.length < 3 || trimmed.length > MAX_KEY_LENGTH) {
+      throw new Error(
+        'systemKey must be 3–40 lowercase letters, digits, or hyphens.'
+      );
+    }
+    instanceKey = trimmed;
+  } else {
+    const slug = slugDisplayName(name);
+    if (!slug) {
+      throw new Error('name is required to derive a Connected System key.');
+    }
+    instanceKey = clipInstanceKey(`${definitionKey}-${slug}`);
+  }
+  assertInstanceKeyNotCatalogKey(definitionKey, instanceKey);
+  return instanceKey;
+}
+
+/**
+ * Derive the instance key and persist it on options.systemKey (never the catalog key).
+ * @param {string} definitionKey
+ * @param {Object} [options]
+ * @returns {string}
+ */
+function resolveChannelInstanceKey(definitionKey, options = {}) {
+  const key = deriveChannelInstanceKey(definitionKey, options.name, options.systemKey);
+  options.systemKey = key;
+  return key;
+}
+
+module.exports = {
+  slugDisplayName,
+  clipInstanceKey,
+  deriveChannelInstanceKey,
+  resolveChannelInstanceKey,
+  assertInstanceKeyNotCatalogKey,
+  INSTANCE_KEY_RE,
+  MAX_KEY_LENGTH,
+  INSTANCE_EQUALS_CATALOG
+};

package/lib/channels/channel-instance-materialize.js

@@ -0,0 +1,240 @@
+/**
+ * Materialize a channel instance package from the definition template.
+ *
+ * @fileoverview Swap instance key; keep channel.definitionKey
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isCommentOrEmptyLine } = require('../utils/secrets-kv-refs');
+
+const DEFERRED_CHANNEL_ENV_KV =
+  /kv:\/\/\S+\/(clientId|clientSecret|tokenUrl|authorizationUrl|botAppId|signingSecret)(\b|$)/i;
+
+/**
+ * @param {string} integrationDir
+ * @param {string} definitionKey
+ * @param {string} instanceKey
+ * @returns {void}
+ */
+function applyInstanceKeyToApplication(integrationDir, definitionKey, instanceKey) {
+  const appPath = path.join(integrationDir, 'application.json');
+  if (!fs.existsSync(appPath)) {
+    return;
+  }
+  const app = JSON.parse(fs.readFileSync(appPath, 'utf8'));
+  if (app.app && typeof app.app === 'object') {
+    app.app.key = instanceKey;
+  }
+  if (app.externalIntegration && Array.isArray(app.externalIntegration.systems)) {
+    app.externalIntegration.systems = app.externalIntegration.systems.map((name) =>
+      name === `${definitionKey}-system.json` ? `${instanceKey}-system.json` : name
+    );
+  }
+  fs.writeFileSync(appPath, `${JSON.stringify(app, null, 2)}\n`);
+}
+
+/**
+ * Stamp catalog identity on the instance ES (channel.definitionKey only).
+ * Package JSON must not include `config` (not in the External System schema).
+ * @param {Object} doc
+ * @param {string} definitionKey
+ * @returns {void}
+ */
+function stampInstanceDefinitionKey(doc, definitionKey) {
+  const channel = doc.channel && typeof doc.channel === 'object' ? { ...doc.channel } : {};
+  channel.definitionKey = definitionKey;
+  doc.channel = channel;
+  delete doc.config;
+}
+
+/**
+ * Bind datasources to the instance key so vendor OpenAPI resolves to openapi/*.json.
+ * Catalog documentKey `{definition}-openapi` + instance systemKey looks for the wrong file.
+ * @param {Object} doc
+ * @param {string} definitionKey
+ * @param {string} instanceKey
+ * @returns {void}
+ */
+function rewriteDatasourceInstanceIdentity(doc, definitionKey, instanceKey) {
+  if (!doc || typeof doc !== 'object') {
+    return;
+  }
+  doc.systemKey = instanceKey;
+  if (!doc.openapi || typeof doc.openapi !== 'object') {
+    return;
+  }
+  const catalogDoc = `${definitionKey}-openapi`;
+  if (doc.openapi.documentKey === catalogDoc) {
+    doc.openapi.documentKey = `${instanceKey}-openapi`;
+  }
+}
+
+/**
+ * @param {string} integrationDir
+ * @param {string} definitionKey
+ * @param {string} instanceKey
+ * @returns {void}
+ */
+function applyInstanceKeyToDatasources(integrationDir, definitionKey, instanceKey) {
+  if (!fs.existsSync(integrationDir)) {
+    return;
+  }
+  for (const name of fs.readdirSync(integrationDir)) {
+    if (!name.includes('-datasource-') || !name.endsWith('.json')) {
+      continue;
+    }
+    const filePath = path.join(integrationDir, name);
+    const doc = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    rewriteDatasourceInstanceIdentity(doc, definitionKey, instanceKey);
+    fs.writeFileSync(filePath, `${JSON.stringify(doc, null, 2)}\n`);
+  }
+}
+
+/**
+ * Secrets written during channel add (Entra/OAuth, Teams botAppId) must not block upload.
+ * @param {string} integrationDir
+ * @returns {void}
+ */
+function commentStaleOauthEnvTemplateLines(integrationDir) {
+  const envPath = path.join(integrationDir, 'env.template');
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+  const original = fs.readFileSync(envPath, 'utf8');
+  const next = original
+    .split('\n')
+    .map((line) => {
+      if (isCommentOrEmptyLine(line)) {
+        return line;
+      }
+      return DEFERRED_CHANNEL_ENV_KV.test(line) ? `# ${line.trim()}` : line;
+    })
+    .join('\n');
+  if (next !== original) {
+    fs.writeFileSync(envPath, next.endsWith('\n') ? next : `${next}\n`);
+  }
+}
+
+/**
+ * @param {string} integrationDir
+ * @param {string} definitionKey
+ * @param {string} instanceKey
+ * @returns {string}
+ */
+function resolveInstanceSystemSource(integrationDir, definitionKey, instanceKey) {
+  const src = path.join(integrationDir, `${definitionKey}-system.json`);
+  const dest = path.join(integrationDir, `${instanceKey}-system.json`);
+  if (fs.existsSync(src)) {
+    return src;
+  }
+  return fs.existsSync(dest) ? dest : '';
+}
+
+/**
+ * @param {string} integrationDir
+ * @param {string} definitionKey
+ * @param {string} instanceKey
+ * @returns {string}
+ */
+function removeLeftoverCatalogDeployJson(integrationDir, definitionKey, instanceKey) {
+  if (definitionKey === instanceKey) {
+    return;
+  }
+  const leftover = path.join(integrationDir, `${definitionKey}-deploy.json`);
+  if (fs.existsSync(leftover)) {
+    fs.unlinkSync(leftover);
+  }
+}
+
+/**
+ * @param {string} integrationDir
+ * @param {string} instanceKey
+ * @returns {string[]}
+ */
+function collectDatasourceIdentityErrors(integrationDir, instanceKey) {
+  const errors = [];
+  for (const name of fs.readdirSync(integrationDir)) {
+    if (!name.includes('-datasource-') || !name.endsWith('.json')) {
+      continue;
+    }
+    const doc = JSON.parse(fs.readFileSync(path.join(integrationDir, name), 'utf8'));
+    if (doc.systemKey !== instanceKey) {
+      errors.push(`${name} systemKey '${doc.systemKey}'`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * @param {string} integrationDir
+ * @param {string} instanceKey
+ * @returns {void}
+ */
+function assertMaterializedInstanceIdentity(integrationDir, instanceKey) {
+  const app = JSON.parse(fs.readFileSync(path.join(integrationDir, 'application.json'), 'utf8'));
+  const system = JSON.parse(
+    fs.readFileSync(path.join(integrationDir, `${instanceKey}-system.json`), 'utf8')
+  );
+  const errors = [];
+  if (app.app && app.app.key !== instanceKey) {
+    errors.push(`application.app.key '${app.app.key}'`);
+  }
+  if (system.key !== instanceKey) {
+    errors.push(`system.key '${system.key}'`);
+  }
+  errors.push(...collectDatasourceIdentityErrors(integrationDir, instanceKey));
+  if (errors.length > 0) {
+    throw new Error(
+      `Channel instance identity must be '${instanceKey}': ${errors.join('; ')}`
+    );
+  }
+}
+
+function maybeAssertMaterializedInstanceIdentity(integrationDir, instanceKey) {
+  const appPath = path.join(integrationDir, 'application.json');
+  const systemPath = path.join(integrationDir, `${instanceKey}-system.json`);
+  if (!fs.existsSync(appPath) || !fs.existsSync(systemPath)) {
+    return;
+  }
+  assertMaterializedInstanceIdentity(integrationDir, instanceKey);
+}
+
+function writeInstanceSystemFile(from, dest, definitionKey, instanceKey) {
+  const doc = JSON.parse(fs.readFileSync(from, 'utf8'));
+  doc.key = instanceKey;
+  stampInstanceDefinitionKey(doc, definitionKey);
+  fs.writeFileSync(dest, `${JSON.stringify(doc, null, 2)}\n`);
+  if (from !== dest && fs.existsSync(from)) {
+    fs.unlinkSync(from);
+  }
+}
+
+function materializeChannelInstanceSystem(integrationDir, definitionKey, instanceKey) {
+  commentStaleOauthEnvTemplateLines(integrationDir);
+  applyInstanceKeyToDatasources(integrationDir, definitionKey, instanceKey);
+  const dest = path.join(integrationDir, `${instanceKey}-system.json`);
+  const from = resolveInstanceSystemSource(integrationDir, definitionKey, instanceKey);
+  if (from) {
+    writeInstanceSystemFile(from, dest, definitionKey, instanceKey);
+  }
+  applyInstanceKeyToApplication(integrationDir, definitionKey, instanceKey);
+  removeLeftoverCatalogDeployJson(integrationDir, definitionKey, instanceKey);
+  maybeAssertMaterializedInstanceIdentity(integrationDir, instanceKey);
+  return dest;
+}
+
+module.exports = {
+  materializeChannelInstanceSystem,
+  applyInstanceKeyToApplication,
+  applyInstanceKeyToDatasources,
+  commentStaleOauthEnvTemplateLines,
+  rewriteDatasourceInstanceIdentity,
+  stampInstanceDefinitionKey,
+  assertMaterializedInstanceIdentity,
+  removeLeftoverCatalogDeployJson
+};

package/lib/channels/channel-integration-generator.js

@@ -1,6 +1,6 @@
 /**
  * Scaffold integration/<channelTarget>/ from published templates (plan 152).
- * Manifest SSOT: dataplane integration/ (slack via make sync-json) → templates/channels/{target}/integration/.
+ * Manifest SSOT: templates/channels/{target}/integration/.
  * Builder generates only *-deploy.json at scaffold time.
  *
  * @fileoverview Channel integration scaffold — template copy + deploy JSON
@@ -10,11 +10,14 @@
 
 'use strict';
 
-const fs = require('fs');
 const path = require('path');
 const { getChannelTarget } = require('./channel-targets');
+const { assertChannelStatusInstallable } = require('./channel-definition-status');
 const { getIntegrationPath } = require('../utils/paths');
-const { copyChannelIntegrationTemplate } = require('./channel-integration-template');
+const {
+  copyChannelIntegrationTemplate,
+  hasChannelIntegrationFiles
+} = require('./channel-integration-template');
 const { generateDeployJson } = require('../generator/index');
 
 /**
@@ -27,22 +30,27 @@ const { generateDeployJson } = require('../generator/index');
  */
 async function scaffoldChannelIntegration(channelTarget, options = {}) {
   const target = getChannelTarget(channelTarget);
+  assertChannelStatusInstallable(channelTarget, options);
   if (target.experimental && !options.allowExperimental) {
     throw new Error(
       `Channel target "${channelTarget}" is experimental. Pass --allow-experimental to scaffold.`
     );
   }
 
-  const integrationDir = options.projectRoot
-    ? path.join(path.resolve(options.projectRoot), 'integration', channelTarget)
-    : getIntegrationPath(channelTarget);
-  if (fs.existsSync(integrationDir) && !options.force) {
+  const integrationDir = options.integrationDir
+    ? path.resolve(options.integrationDir)
+    : options.projectRoot
+      ? path.join(path.resolve(options.projectRoot), 'integration', channelTarget)
+      : getIntegrationPath(channelTarget);
+  if (hasChannelIntegrationFiles(integrationDir, channelTarget) && !options.force) {
     throw new Error(
       `Integration folder already exists: ${integrationDir}. Use --force to overwrite generated files.`
     );
   }
 
-  const copied = copyChannelIntegrationTemplate(channelTarget, integrationDir);
+  const copied = copyChannelIntegrationTemplate(channelTarget, integrationDir, {
+    overwrite: options.force === true
+  });
   const deployPath = await generateDeployJson(channelTarget, { appPath: integrationDir });
   const files = [...copied, deployPath];
 
@@ -53,5 +61,6 @@ async function scaffoldChannelIntegration(channelTarget, options = {}) {
 }
 
 module.exports = {
-  scaffoldChannelIntegration
+  scaffoldChannelIntegration,
+  hasChannelIntegrationFiles
 };