@aifabrix/builder 2.51.1 → 2.52.1

package/lib/app/run-env-recovery.js

@@ -0,0 +1,35 @@
+/**
+ * Last-moment run env recovery for the shared applications workspace.
+ *
+ * @fileoverview Builds the callback used immediately before Docker Compose starts
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const runEnvCompose = require('./run-env-compose');
+
+/**
+ * Build a recovery hook for run env files in the shared workspace.
+ * @param {string} appName - Application name
+ * @param {Object} prepared - Prepared run context
+ * @returns {Function} Async recovery hook
+ */
+function buildRunEnvRecovery(appName, prepared) {
+  return () =>
+    runEnvCompose.ensureRunEnvFilesPresent(
+      appName,
+      prepared.appConfig,
+      prepared.runEnvPath,
+      prepared.runEnvAdminPath,
+      prepared.appConfig.developerId,
+      {
+        runEnvKey: prepared.mergedRunOptions.env,
+        effectiveEnvironmentScopedResources:
+          prepared.mergedRunOptions.effectiveEnvironmentScopedResources
+      }
+    );
+}
+
+module.exports = { buildRunEnvRecovery };

package/lib/app/run-helpers.js

@@ -253,18 +253,17 @@ async function checkInfraHealthOrThrow(debug, appConfig) {
 }
 
 /**
- * Ensure dev directory exists
+ * Refresh the shared developer run directory for the current application.
+ *
+ * The applications-dev-* directory is shared by all applications. Always copy
+ * the selected app so files from a previous run cannot leak into this run.
  * @async
  * @param {string} appName - Application name
  * @param {string} developerId - Developer ID
  * @returns {Promise<string>} Dev directory path
  */
 async function ensureDevDirectory(appName, developerId) {
-  const devDir = buildCopy.getDevDirectory(appName, developerId);
-  if (!fsSync.existsSync(devDir)) {
-    await buildCopy.copyBuilderToDevDirectory(appName, developerId);
-  }
-  return devDir;
+  return buildCopy.copyBuilderToDevDirectory(appName, developerId);
 }
 
 /**

package/lib/app/run.js

@@ -28,6 +28,7 @@ const helpers = require('./run-helpers');
 const { ensureReloadSync, logReloadDevSummary } = require('./run-reload-sync');
 const { logRestartDevMountSummary } = require('./restart-display');
 const { checkAndStopContainer } = require('./run-stop-containers');
+const { buildRunEnvRecovery } = require('./run-env-recovery');
 const { execWithDockerEnv } = require('../utils/docker-exec');
 const { resolveRunProxyPersistEnabled, resolveRunEffectiveNoProxy } = require('../utils/run-cli-flags');
 
@@ -178,7 +179,8 @@ async function startAppContainer(appName, tempComposePath, hostPort, appConfig,
     runEnvPath = null,
     runEnvAdminPath = null,
     runOptions = {},
-    devMountPath = null
+    devMountPath = null,
+    ensureRunEnvFiles = null
   } = opts;
   const misoEnvironment = opts.misoEnvironment ?? composeGenerator.resolveMisoEnvironment(runOptions);
   try {
@@ -188,6 +190,7 @@ async function startAppContainer(appName, tempComposePath, hostPort, appConfig,
       runEnvAdminPath,
       runOptions,
       devMountPath,
+      ensureRunEnvFiles,
       misoEnvironment
     });
     await helpers.displayRunStatus(
@@ -410,15 +413,20 @@ async function runApp(appName, options = {}) {
       fullImage: prepared.mergedRunOptions.image,
       runEnvPath: prepared.runEnvPath,
       devMountPath: prepared.devMountPath || null,
-      debug
+      debug,
+      // Guided installers already show a top-level spinner; keep migrate/deployJob logs out of TTY.
+      quiet:
+        options.silentPoll === true || typeof options.onPollText === 'function'
     });
+    const ensureRunEnvFiles = buildRunEnvRecovery(appName, prepared);
     await startAppContainer(appName, prepared.tempComposePath, prepared.hostPort, prepared.appConfig, {
       debug,
       runEnvPath: prepared.runEnvPath,
       runEnvAdminPath: prepared.runEnvAdminPath,
       runOptions: prepared.mergedRunOptions,
       devMountPath: prepared.devMountPath,
-      runScopeOpts: prepared.runScopeOpts
+      runScopeOpts: prepared.runScopeOpts,
+      ensureRunEnvFiles
     });
   } catch (error) {
     if (debug) {

package/lib/channels/add-channel.js

@@ -10,9 +10,15 @@
 
 const { getChannelTarget, getDefaultChannelDescription } = require('./channel-targets');
 const { resolveAppDescription } = require('./channel-description');
+const path = require('path');
 const { resolveChannelRuntimeValues } = require('./channel-runtime-resolver');
 const { generateChannelArtifact } = require('./channel-artifact-generator');
 const { fetchRuntimeLayerBToolNames } = require('./runtime-tool-catalog');
+const { loadChannelPackageContext } = require('./channel-discovery');
+const {
+  readChannelBranding,
+  mergeChannelBranding
+} = require('./channel-branding');
 const {
   getExistingChannelExtension,
   buildChannelExtensionBlock,
@@ -39,9 +45,14 @@ const {
 } = require('./channel-display-name');
 const {
   displayExistingChannelStatus,
-  displayChannelInstallResult,
-  displayChannelError
+  displayChannelInstallResult
 } = require('./channel-status-display');
+const { ensureChannelReadyForAdd } = require('./channel-add-ensure');
+const {
+  assertMicrosoftCopilotOauthReference,
+  assertMicrosoftCopilotOauthReferenceBeforeForce,
+  loadMicrosoftCopilotEntraContext
+} = require('./microsoft-copilot-channel-add');
 
 /**
  * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
@@ -252,6 +263,9 @@ async function completeLiveInstall(params) {
     capabilities: target.capabilities,
     artifactPath: artifact.outputPath,
     installGuidePath: artifact.installPath,
+    zipPath: artifact.zipPath,
+    installReady: artifact.installReady,
+    blocker: artifact.blocker,
     validation: toValidationDisplay(validation),
     approvalGuide
   });
@@ -272,7 +286,10 @@ function finishDryRunInstall(params) {
     credentialKey: params.target.credentialKey,
     capabilities: params.target.capabilities,
     artifactPath: params.artifact.outputPath,
-    installGuidePath: params.artifact.installPath
+    installGuidePath: params.artifact.installPath,
+    zipPath: params.artifact.zipPath,
+    installReady: params.artifact.installReady,
+    blocker: params.artifact.blocker
   });
   return { dryRun: true, channelBlock: params.channelBlock, artifact: params.artifact };
 }
@@ -281,12 +298,78 @@ function finishDryRunInstall(params) {
  * @param {Object} params
  * @returns {Promise<{ artifact: Object, channelBlock: Object, status: string }>}
  */
+/**
+ * @param {Object|null} packageContext
+ * @param {Object} options
+ * @param {'iconColorPath'|'iconOutlinePath'} key
+ * @returns {string|undefined}
+ */
+function brandingIconOrOption(packageContext, options, key) {
+  if (typeof options[key] === 'string' && options[key].trim()) {
+    return options[key].trim();
+  }
+  if (packageContext && typeof packageContext[key] === 'string' && packageContext[key].trim()) {
+    return packageContext[key].trim();
+  }
+  return undefined;
+}
+
+async function resolvePackageContextForInstall(params) {
+  const { channelTarget, options, name, description, ctx } = params;
+  const packagingTargets = new Set(['chatgpt', 'microsoft-copilot', 'slack', 'teams-bot']);
+  if (!packagingTargets.has(channelTarget)) {
+    return null;
+  }
+  const projectRoot = options.projectRoot || process.cwd();
+  const workspaceDir = path.join(projectRoot, 'integration', channelTarget);
+  const branding = mergeChannelBranding(readChannelBranding(workspaceDir), {
+    displayName: options.overrideDisplayName || undefined,
+    description: options.overrideDescription || undefined,
+    iconColorPath: options.iconColorPath || undefined,
+    iconOutlinePath: options.iconOutlinePath || undefined
+  });
+  let packageContext;
+  try {
+    packageContext = await loadChannelPackageContext({
+      dataplaneBaseUrl: ctx.dataplaneUrl,
+      authConfig: ctx.authConfig,
+      channelTarget,
+      branding
+    });
+  } catch {
+    packageContext = {
+      displayName: name,
+      description,
+      governedToolNames: [],
+      mcpServerUrl: null,
+      installReady: false,
+      blocker: 'discoveryUnavailable',
+      authentication: null,
+      authenticationCapabilities: []
+    };
+  }
+  return {
+    ...packageContext,
+    iconColorPath: branding.iconColorPath,
+    iconOutlinePath: branding.iconOutlinePath
+  };
+}
+
 async function buildInstallArtifacts(params) {
   const { channelTarget, options, target, existing, name, baseName, description, ctx } = params;
-  const runtimeToolNames =
-    channelTarget === 'chatgpt' || channelTarget === 'microsoft-copilot'
-      ? await fetchRuntimeLayerBToolNames(ctx.dataplaneUrl, ctx.authConfig, channelTarget)
-      : [];
+  const packageContext = await resolvePackageContextForInstall(params);
+  let runtimeToolNames = [];
+  if (channelTarget === 'chatgpt' || channelTarget === 'microsoft-copilot') {
+    runtimeToolNames =
+      packageContext?.governedToolNames?.length > 0
+        ? packageContext.governedToolNames
+        : await fetchRuntimeLayerBToolNames(ctx.dataplaneUrl, ctx.authConfig, channelTarget);
+  }
+  let entraProvider = null;
+  let entraIdentityProvider = null;
+  if (channelTarget === 'microsoft-copilot') {
+    ({ entraProvider, entraIdentityProvider } = await loadMicrosoftCopilotEntraContext(ctx));
+  }
   const runtimeValues = resolveChannelRuntimeValues({
     dataplaneBaseUrl: ctx.dataplaneUrl,
     channelTarget,
@@ -296,7 +379,14 @@ async function buildInstallArtifacts(params) {
     appDescription: description,
     icon: options.icon,
     commandPrefix: options.commandPrefix,
-    layerBToolNames: runtimeToolNames
+    layerBToolNames: runtimeToolNames,
+    packageContext,
+    entraProvider,
+    entraIdentityProvider,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
+    scopes: options.scopes,
+    iconColorPath: brandingIconOrOption(packageContext, options, 'iconColorPath'),
+    iconOutlinePath: brandingIconOrOption(packageContext, options, 'iconOutlinePath')
   });
   const projectRoot = options.projectRoot || process.cwd();
   const artifact = generateArtifactWithAudit(channelTarget, {
@@ -313,17 +403,39 @@ async function buildInstallArtifacts(params) {
   return { artifact, channelBlock, status };
 }
 
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Object}
+ */
+function assertChannelAddOptions(channelTarget, options) {
+  const target = getChannelTarget(channelTarget);
+  if (target.experimental) {
+    throw new Error(
+      `Channel target "${channelTarget}" is experimental. Confirm product requirement before use.`
+    );
+  }
+  if (!options.name || typeof options.name !== 'string' || !options.name.trim()) {
+    throw new Error('--name is required for channel add');
+  }
+  return target;
+}
+
 /**
  * @param {string} channelTarget
  * @param {Object} options
  * @returns {Promise<Object>}
  */
 async function runAddChannel(channelTarget, options = {}) {
-  const { target, name, baseName, description, ctx, existing } = await prepareChannelContext(
+  const target = assertChannelAddOptions(channelTarget, options);
+  if (channelTarget === 'microsoft-copilot' && options.force === true) {
+    await assertMicrosoftCopilotOauthReferenceBeforeForce(options);
+  }
+  await ensureChannelReadyForAdd(channelTarget, options);
+  const { name, baseName, description, ctx, existing } = await prepareChannelContext(
     channelTarget,
     options
   );
-
   const skipped = showExistingChannelStatus({
     existing,
     options,
@@ -333,7 +445,9 @@ async function runAddChannel(channelTarget, options = {}) {
     ctx
   });
   if (skipped) return skipped;
-
+  if (channelTarget === 'microsoft-copilot') {
+    await assertMicrosoftCopilotOauthReference({ options, ctx, name, baseName, description });
+  }
   const { artifact, channelBlock, status } = await buildInstallArtifacts({
     channelTarget,
     options,
@@ -344,11 +458,9 @@ async function runAddChannel(channelTarget, options = {}) {
     description,
     ctx
   });
-
   if (options.dryRun) {
     return finishDryRunInstall({ channelTarget, name, baseName, target, artifact, channelBlock });
   }
-
   return completeLiveInstall({
     ctx,
     channelTarget,
@@ -367,12 +479,7 @@ async function runAddChannel(channelTarget, options = {}) {
  * @param {Object} options
  */
 async function addChannelCommand(channelTarget, options = {}) {
-  try {
-    await runAddChannel(channelTarget, options);
-  } catch (err) {
-    displayChannelError(err.message || String(err));
-    throw err;
-  }
+  await runAddChannel(channelTarget, options);
 }
 
 module.exports = {

package/lib/channels/approval-guides/chatgpt.js

@@ -16,17 +16,20 @@ const { formatCredentialPortalStep } = require('./credential-portal');
  */
 function buildChatGptApprovalGuide(ctx) {
   return {
-    portalUrl: 'https://platform.openai.com/',
+    portalUrl: 'https://chatgpt.com/',
     steps: [
-      'Sign in to OpenAI Platform (https://platform.openai.com/) or your ChatGPT Enterprise workspace admin console.',
-      'Enable Developer mode / custom MCP app creation for the workspace (if policy requires admin allow-listing).',
-      'Create a custom MCP app using the generated channel-chatgpt.json reference artifact (path shown below).',
-      'Configure the Runtime MCP endpoint from INSTALL.md and verify Runtime Layer B tool discovery.',
-      'Complete workspace authentication setup for the custom MCP app.',
-      formatCredentialPortalStep(ctx, 'workspace credential references used by the ChatGPT channel'),
-      'Publish the app to your workspace and configure end-user access controls.',
+      'Sign in to the ChatGPT web app as a workspace admin or owner.',
+      'Enable Developer mode for custom MCP apps (Business: Workspace settings → Apps, or Settings → Apps → Advanced settings; Enterprise/Edu: grant Developer mode under Permissions & roles → Connected data first).',
+      'Create a custom MCP app with the Remote MCP URL from INSTALL.md (channel-chatgpt.json is a deployment reference, not a plugin archive).',
+      'Select OAuth (authorization-code + PKCE S256). Do not configure a custom API key for a remote custom MCP app.',
+      'Scan tools, complete OAuth if prompted, review discovered governed tools, then save the app as a draft.',
+      formatCredentialPortalStep(
+        ctx,
+        `${ctx.credentialKey || 'channel'} credential references (not secrets to paste into ChatGPT)`
+      ),
+      'Test representative workflows, then publish the app and configure workspace access and action controls.',
       `After ChatGPT lists the app as active, re-run: ${ctx.resumeCommand}`,
-      'Optional: use --probe for AI Fabrix-side runtime checks; OpenAI-side publication remains a manual admin responsibility.'
+      'Optional: use --probe for AI Fabrix-side Runtime checks; ChatGPT Scan tools / OAuth / publication remain workspace-admin responsibilities.'
     ]
   };
 }

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

@@ -1,14 +1,16 @@
 /**
- * Microsoft Copilot channel admin approval steps (plan 152).
+ * Microsoft Copilot channel install / approval steps.
  *
- * @fileoverview Copilot Studio / M365 admin connector guide
+ * @fileoverview Teams custom-app upload guide aligned with install templates
  * @author AI Fabrix Team
  * @version 1.0.0
  */
 
 'use strict';
 
-const { formatCredentialPortalStep } = require('./credential-portal');
+const {
+  ENTRA_SSO_REGISTRATION_URL
+} = require('../microsoft-copilot-entra-sso-form');
 
 /**
  * @param {Object} ctx
@@ -16,16 +18,18 @@ const { formatCredentialPortalStep } = require('./credential-portal');
  */
 function buildMicrosoftCopilotApprovalGuide(ctx) {
   return {
-    portalUrl: 'https://admin.cloud.microsoft.com/',
+    portalUrl: ENTRA_SSO_REGISTRATION_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 Microsoft Teams with your target Microsoft 365 account.',
+      'Go to Apps → Manage your apps → Upload an app → Upload a custom app.',
+      'Upload only appPackage.<env>.zip (do not upload individual manifest files or channel-microsoft-copilot.json).',
+      'Review permissions, select Add, and open the installed app. Users stay on the Microsoft 365 Entra session — no separate AI Fabrix sign-in.',
+      'If prompted, complete Entra admin consent for the Runtime MCP delegated scope.',
+      'If Upload a custom app is unavailable, ask a Teams admin to enable custom app uploads or deploy the package centrally.',
+      `Register Entra SSO first at ${ENTRA_SSO_REGISTRATION_URL} using the Base URL / Client ID / Scope values printed by the CLI (or INSTALL.md). Pass the registration id as --oauth-plugin-vault-reference-id.`,
+      'Do not configure AI Fabrix OAuth client secrets under Connected Systems → Authentication for this Entra SSO flow.',
+      'Confirm Runtime MCP and governed tools using INSTALL.md, then re-run with --probe after Teams install.',
+      `After the app is available in Teams, re-run: ${ctx.resumeCommand}`
     ]
   };
 }

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