@aifabrix/builder 2.52.0 → 2.53.0

package/lib/channels/approval-guides/microsoft-copilot.js

@@ -1,33 +1,46 @@
 /**
- * Microsoft Copilot channel admin approval steps (plan 152).
+ * Microsoft Copilot channel install / approval steps.
  *
- * @fileoverview Copilot Studio / M365 admin connector guide
+ * @fileoverview Organisation publish via Developer Portal + Teams admin approval
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.2.0
  */
 
 'use strict';
 
-const { formatCredentialPortalStep } = require('./credential-portal');
+const DEVELOPER_PORTAL_URL = 'https://dev.teams.microsoft.com/';
+const TEAMS_ADMIN_APPS_URL = 'https://admin.teams.microsoft.com/policies/manage-apps';
 
 /**
  * @param {Object} ctx
  * @returns {{ portalUrl: string, steps: string[] }}
  */
 function buildMicrosoftCopilotApprovalGuide(ctx) {
+  const env = typeof ctx.environment === 'string' && ctx.environment.trim()
+    ? ctx.environment.trim()
+    : 'dev';
+  const zipName = `appPackage.${env}.zip`;
+  const appName =
+    (typeof ctx.name === 'string' && ctx.name.trim()) ||
+    (typeof ctx.baseName === 'string' && ctx.baseName.trim()) ||
+    'your app';
   return {
-    portalUrl: 'https://admin.cloud.microsoft.com/',
+    portalUrl: DEVELOPER_PORTAL_URL,
     steps: [
-      'Sign in to Microsoft 365 admin (https://admin.cloud.microsoft.com/) or Copilot Studio as a tenant admin.',
-      'Upload or sideload the generated appPackage.<env>.zip package artifact.',
-      'Review declarative agent + Remote MCP plugin details and approve tenant distribution.',
-      'Configure Entra/OAuth consent and user assignment for target groups.',
-      formatCredentialPortalStep(ctx, 'Copilot channel credential references (no secrets in package files)'),
-      'Verify Runtime MCP endpoint and Layer B tool visibility using INSTALL.md guidance.',
-      `After Copilot shows the package as available, re-run: ${ctx.resumeCommand}`,
-      'Optional: use --probe for AI Fabrix-side checks; tenant upload/approval remains Microsoft-admin responsibility.'
+      `Open Teams Developer Portal (${DEVELOPER_PORTAL_URL}).`,
+      `Click Import an app → import ${zipName}. Preserve the generated stable manifest.json.id. Do not create an unrelated new Teams app.`,
+      'Developer Portal → selected app → Publish to your org → Distribute / submit.',
+      `Teams admin approves in ${TEAMS_ADMIN_APPS_URL} (Manage apps → search → allow). Expect Published / Unblocked per organisation policy. Allow several minutes for propagation.`,
+      `Open Teams → Apps (Built for your org), click "${appName}", Add the application, then choose Open with Copilot.`,
+      'In Copilot, click "Show my role assistants" and run the command.',
+      'Confirm Runtime MCP and governed tools using INSTALL.md, then re-run with --probe after organisation publish.',
+      `After the app is available under Built for your org, re-run: ${ctx.resumeCommand}`
     ]
   };
 }
 
-module.exports = { buildMicrosoftCopilotApprovalGuide };
+module.exports = {
+  buildMicrosoftCopilotApprovalGuide,
+  DEVELOPER_PORTAL_URL,
+  TEAMS_ADMIN_APPS_URL
+};

package/lib/channels/channel-add-ensure.js

@@ -0,0 +1,128 @@
+/**
+ * Ensure local scaffold + dataplane upload before channel add install.
+ *
+ * @fileoverview One-command channel add prelude (scaffold → upload if needed)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { formatSuccessLine, metadata } = require('../utils/cli-test-layout-chalk');
+const { getIntegrationPath } = require('../utils/paths');
+const { getExternalSystem } = require('../api/external-systems.api');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+const { scaffoldChannelIntegration } = require('./channel-integration-generator');
+const { resolveChannelAuthContext } = require('./channel-auth-context');
+const { uploadExternalSystem } = require('../commands/upload');
+
+/**
+ * @param {string} channelTarget
+ * @param {string} [projectRoot]
+ * @returns {string}
+ */
+function resolveIntegrationDir(channelTarget, projectRoot) {
+  if (projectRoot) {
+    return path.join(path.resolve(projectRoot), 'integration', channelTarget);
+  }
+  return getIntegrationPath(channelTarget);
+}
+
+/**
+ * @param {Object} ctx
+ * @param {string} channelTarget
+ * @returns {Promise<boolean>}
+ */
+async function isCommunicationSystemUploaded(ctx, channelTarget) {
+  const res = await getExternalSystem(ctx.dataplaneUrl, channelTarget, ctx.authConfig);
+  const system = unwrapApiData(res);
+  return !!(system && typeof system === 'object');
+}
+
+/**
+ * Scaffold integration/<target>/ when missing (does not overwrite).
+ *
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<{ scaffolded: boolean, integrationDir: string }>}
+ */
+async function ensureChannelScaffold(channelTarget, options = {}) {
+  const integrationDir = resolveIntegrationDir(channelTarget, options.projectRoot);
+  if (fs.existsSync(integrationDir)) {
+    return { scaffolded: false, integrationDir };
+  }
+  const result = await scaffoldChannelIntegration(channelTarget, {
+    projectRoot: options.projectRoot,
+    allowExperimental: options.allowExperimental === true
+  });
+  if (options.quiet !== true) {
+    logger.log(formatSuccessLine(`Scaffolded integration at ${result.integrationDir}`));
+    for (const file of result.files) {
+      logger.log(metadata(file));
+    }
+  }
+  return { scaffolded: true, integrationDir: result.integrationDir };
+}
+
+/**
+ * Upload when missing on dataplane; with --force upload every time.
+ *
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<{ uploaded: boolean, skipped: boolean, ctx: Object|null }>}
+ */
+async function ensureChannelUploaded(channelTarget, options = {}) {
+  if (options.dryRun === true) {
+    return { uploaded: false, skipped: true, ctx: null };
+  }
+  const ctx = await resolveChannelAuthContext(channelTarget, { silent: options.quiet === true });
+  const force = options.force === true;
+  const alreadyUploaded = force ? false : await isCommunicationSystemUploaded(ctx, channelTarget);
+  if (alreadyUploaded) {
+    if (options.quiet !== true) {
+      logger.log(chalk.gray(`  Communication system "${channelTarget}" already on dataplane`));
+    }
+    return { uploaded: false, skipped: true, ctx };
+  }
+  if (options.quiet !== true) {
+    const reason = force ? 'force upload' : 'not found on dataplane';
+    logger.log(chalk.white(`Uploading ${channelTarget} (${reason})…`));
+  }
+  await uploadExternalSystem(channelTarget, {
+    force: true,
+    minimal: options.quiet === true || options.minimal !== false
+  });
+  if (options.quiet !== true) {
+    logger.log(formatSuccessLine(`Uploaded ${channelTarget}`));
+  }
+  return { uploaded: true, skipped: false, ctx };
+}
+
+/**
+ * Scaffold if needed, then upload if missing (or always when --force).
+ *
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<{ scaffolded: boolean, uploaded: boolean, integrationDir: string }>}
+ */
+async function ensureChannelReadyForAdd(channelTarget, options = {}) {
+  const scaffold = await ensureChannelScaffold(channelTarget, options);
+  const upload = await ensureChannelUploaded(channelTarget, options);
+  return {
+    scaffolded: scaffold.scaffolded,
+    uploaded: upload.uploaded,
+    integrationDir: scaffold.integrationDir
+  };
+}
+
+module.exports = {
+  resolveIntegrationDir,
+  isCommunicationSystemUploaded,
+  ensureChannelScaffold,
+  ensureChannelUploaded,
+  ensureChannelReadyForAdd
+};

package/lib/channels/channel-add-existing.js

@@ -0,0 +1,72 @@
+/**
+ * Existing-channel skip path for aifabrix channel add.
+ *
+ * @fileoverview Keep add-channel.js under the 500-line limit
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getArtifactOutputPath } = require('./channel-artifact-generator');
+const { buildChannelApprovalGuide } = require('./channel-approval-guide');
+const { displayExistingChannelStatus } = require('./channel-status-display');
+
+/**
+ * True when local channel package files are present under dist/channels/<target>/.
+ * @param {string} projectRoot
+ * @param {string} channelTarget
+ * @returns {boolean}
+ */
+function localChannelArtifactsExist(projectRoot, channelTarget) {
+  const summaryPath = getArtifactOutputPath(projectRoot, channelTarget);
+  const installPath = path.join(path.dirname(summaryPath), 'INSTALL.md');
+  return fs.existsSync(summaryPath) && fs.existsSync(installPath);
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object|null}
+ */
+function showExistingChannelStatus(params) {
+  const { existing, options, channelTarget, name, baseName, ctx } = params;
+  if (!existing || options.force || options.dryRun) return null;
+  const sameInstall =
+    (existing.baseName && existing.baseName === baseName) ||
+    (!existing.baseName && existing.name === name);
+  if (!sameInstall) {
+    throw new Error(
+      `Channel already configured as "${existing.name}". ` +
+        `Use --force to replace with "${name}".`
+    );
+  }
+  const projectRoot = options.projectRoot || process.cwd();
+  // Dataplane may still have the channel while local dist/ was deleted — regenerate.
+  if (!localChannelArtifactsExist(projectRoot, channelTarget)) {
+    return null;
+  }
+  const approvalGuide =
+    existing.status === 'approvalRequired'
+      ? buildChannelApprovalGuide(channelTarget, {
+        projectRoot,
+        name: existing.name || name,
+        baseName,
+        dataplaneBaseUrl: ctx?.dataplaneUrl,
+        environment: ctx?.environment || 'dev'
+      })
+      : null;
+  displayExistingChannelStatus({
+    channelTarget,
+    name: existing.name || name,
+    channelExt: existing,
+    approvalGuide
+  });
+  return { skipped: true, channelExt: existing };
+}
+
+module.exports = {
+  localChannelArtifactsExist,
+  showExistingChannelStatus
+};

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

@@ -147,11 +147,21 @@ function generateChannelArtifact(params) {
     params.dryRun === true
   );
 
+  const installReady = params.runtimeValues?.installReady === true;
+  const blocker = params.runtimeValues?.discoveryBlocker || null;
   return {
     outputPath,
     artifactHash,
     content,
-    installPath: install?.installPath
+    installPath: install?.installPath,
+    zipPath: null,
+    links: {
+      readme: install?.installPath || null,
+      zip: null,
+      filesRoot: outputDir
+    },
+    installReady,
+    blocker
   };
 }
 

package/lib/channels/channel-branding.js

@@ -0,0 +1,94 @@
+/**
+ * Optional channel package branding in Builder workspace (plan 167.0).
+ *
+ * @fileoverview Read/write channel-branding.json under integration/<systemKey>/
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+
+const BRANDING_FILENAME = 'channel-branding.json';
+
+/**
+ * @param {string} workspaceSystemDir
+ * @returns {string}
+ */
+function brandingFilePath(workspaceSystemDir) {
+  return path.join(workspaceSystemDir, BRANDING_FILENAME);
+}
+
+/**
+ * @param {string} workspaceSystemDir
+ * @returns {{ displayName?: string, description?: string, iconColorPath?: string, iconOutlinePath?: string }}
+ */
+function readChannelBranding(workspaceSystemDir) {
+  const filePath = brandingFilePath(workspaceSystemDir);
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  if (!raw || typeof raw !== 'object') {
+    return {};
+  }
+  /** @type {{ displayName?: string, description?: string, iconColorPath?: string, iconOutlinePath?: string }} */
+  const out = {};
+  if (typeof raw.displayName === 'string' && raw.displayName.trim()) {
+    out.displayName = raw.displayName.trim();
+  }
+  if (typeof raw.description === 'string' && raw.description.trim()) {
+    out.description = raw.description.trim();
+  }
+  if (typeof raw.iconColorPath === 'string' && raw.iconColorPath.trim()) {
+    out.iconColorPath = raw.iconColorPath.trim();
+  }
+  if (typeof raw.iconOutlinePath === 'string' && raw.iconOutlinePath.trim()) {
+    out.iconOutlinePath = raw.iconOutlinePath.trim();
+  }
+  return out;
+}
+
+/**
+ * @param {string} workspaceSystemDir
+ * @param {Object} branding
+ * @returns {Object}
+ */
+function writeChannelBranding(workspaceSystemDir, branding) {
+  fs.mkdirSync(workspaceSystemDir, { recursive: true });
+  const next = {
+    ...readChannelBranding(workspaceSystemDir),
+    ...(branding && typeof branding === 'object' ? branding : {})
+  };
+  const cleaned = {};
+  for (const key of ['displayName', 'description', 'iconColorPath', 'iconOutlinePath']) {
+    if (typeof next[key] === 'string' && next[key].trim()) {
+      cleaned[key] = next[key].trim();
+    }
+  }
+  fs.writeFileSync(brandingFilePath(workspaceSystemDir), `${JSON.stringify(cleaned, null, 2)}\n`, 'utf8');
+  return cleaned;
+}
+
+/**
+ * Merge CLI/API overrides over workspace branding.
+ * @param {Object} [workspaceBranding]
+ * @param {Object} [overrides]
+ * @returns {Object}
+ */
+function mergeChannelBranding(workspaceBranding, overrides) {
+  return {
+    ...(workspaceBranding && typeof workspaceBranding === 'object' ? workspaceBranding : {}),
+    ...(overrides && typeof overrides === 'object' ? overrides : {})
+  };
+}
+
+module.exports = {
+  BRANDING_FILENAME,
+  brandingFilePath,
+  readChannelBranding,
+  writeChannelBranding,
+  mergeChannelBranding
+};

package/lib/channels/channel-credential.js

@@ -18,6 +18,7 @@ const {
   auditCredentialUpdated,
   auditFailed
 } = require('./channel-audit');
+const { skipsChannelOauthCredential } = require('./microsoft-copilot-entra-sso');
 
 /** @type {Record<string, { method: string, displayName: string, credentialConfig: Object }>} */
 const CREDENTIAL_SPECS = {
@@ -171,6 +172,13 @@ async function pushIntegrationSecrets(ctx, channelTarget) {
  */
 async function ensureChannelCredential(params) {
   const { ctx, channelTarget, target, force = false } = params;
+  if (skipsChannelOauthCredential(channelTarget)) {
+    return {
+      skipped: true,
+      reason: 'entraSsoTrustedIssuer',
+      credentialKey: target.credentialKey
+    };
+  }
   const existing = await findCredentialByKey(ctx, target.credentialKey);
   if (existing) {
     auditCredentialUpdated(channelTarget, {