@aifabrix/builder 2.51.1 → 2.52.1

package/lib/channels/microsoft-copilot-limits.js

@@ -0,0 +1,84 @@
+/**
+ * Microsoft Copilot / Teams package string limits.
+ *
+ * @fileoverview Truncate and normalize Copilot package display fields to schema limits
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const TEAMS_NAME_SHORT_MAX = 30;
+const TEAMS_NAME_FULL_MAX = 100;
+const TEAMS_DESCRIPTION_SHORT_MAX = 80;
+const TEAMS_DESCRIPTION_FULL_MAX = 4000;
+const PLUGIN_NAME_FOR_HUMAN_MAX = 20;
+const PLUGIN_DESCRIPTION_FOR_HUMAN_MAX = 100;
+
+/**
+ * @param {string} text
+ * @param {number} max
+ * @returns {string}
+ */
+function truncateForSchema(text, max) {
+  const value = String(text ?? '').trim();
+  if (!value) return '';
+  if (value.length <= max) return value;
+  if (max <= 1) return value.slice(0, max);
+  return `${value.slice(0, max - 1)}…`;
+}
+
+/**
+ * Plugin namespace: lowercase alphanumeric/hyphen only (plugin schema ^[A-Za-z0-9-]+$).
+ * @param {string} baseName
+ * @returns {string}
+ */
+function buildPluginNamespace(baseName) {
+  const raw = String(baseName ?? 'aifabrix')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  const ns = raw || 'aifabrix';
+  return truncateForSchema(ns, 32).replace(/[^a-z0-9-]/g, '') || 'aifabrix';
+}
+
+/**
+ * @param {Object} runtimeValues
+ * @returns {Object}
+ */
+function applyMicrosoftCopilotDisplayLimits(runtimeValues) {
+  const appDescription = String(runtimeValues.appDescription || '').trim();
+  const baseName = String(runtimeValues.baseName || runtimeValues.appName || 'Assistant').trim();
+  const appName = String(runtimeValues.appName || baseName).trim();
+  runtimeValues.shortName = truncateForSchema(baseName, TEAMS_NAME_SHORT_MAX);
+  runtimeValues.fullName = truncateForSchema(appName, TEAMS_NAME_FULL_MAX);
+  runtimeValues.shortDescription = truncateForSchema(
+    appDescription || 'Enterprise AI assistant via AI Fabrix Runtime.',
+    TEAMS_DESCRIPTION_SHORT_MAX
+  );
+  runtimeValues.fullDescription = truncateForSchema(
+    appDescription || runtimeValues.shortDescription,
+    TEAMS_DESCRIPTION_FULL_MAX
+  );
+  runtimeValues.pluginNameForHuman = truncateForSchema(baseName, PLUGIN_NAME_FOR_HUMAN_MAX);
+  runtimeValues.pluginDescriptionForHuman = truncateForSchema(
+    appDescription || runtimeValues.shortDescription,
+    PLUGIN_DESCRIPTION_FOR_HUMAN_MAX
+  );
+  runtimeValues.pluginNamespace = buildPluginNamespace(baseName);
+  return runtimeValues;
+}
+
+module.exports = {
+  TEAMS_NAME_SHORT_MAX,
+  TEAMS_NAME_FULL_MAX,
+  TEAMS_DESCRIPTION_SHORT_MAX,
+  TEAMS_DESCRIPTION_FULL_MAX,
+  PLUGIN_NAME_FOR_HUMAN_MAX,
+  PLUGIN_DESCRIPTION_FOR_HUMAN_MAX,
+  truncateForSchema,
+  buildPluginNamespace,
+  applyMicrosoftCopilotDisplayLimits
+};

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

@@ -9,12 +9,16 @@
 'use strict';
 
 const crypto = require('crypto');
-const fs = require('fs');
+const fs = require('../internal/fs-real-sync');
 const path = require('path');
 const AdmZip = require('adm-zip');
-
-const PLACEHOLDER_ICON_BASE64 =
-  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO2s9WQAAAAASUVORK5CYII=';
+const { getMicrosoftCopilotIcons } = require('./microsoft-copilot-icons');
+const { assertValidMicrosoftCopilotPackage } = require('./microsoft-copilot-validate');
+const { applyMicrosoftCopilotDisplayLimits } = require('./microsoft-copilot-limits');
+const {
+  assertCopilotPackageOauthPluginVaultReference
+} = require('./microsoft-copilot-entra-sso');
+const { renderCopilotChannelTemplate } = require('./microsoft-copilot-entra-sso-form');
 
 /**
  * @param {string} outputPath
@@ -37,16 +41,20 @@ function buildCopilotOutputPaths(outputPath, runtimeValues) {
     zipFileName,
     zipPath: path.join(buildDir, zipFileName),
     validationPath: path.join(installDir, 'validation.json'),
-    installPath: path.join(installDir, 'README.md')
+    installPath: path.join(rootDir, 'INSTALL.md'),
+    installReadmePath: path.join(installDir, 'README.md')
   };
 }
 
 /**
+ * @param {Object} [runtimeValues]
  * @returns {{ color: Buffer, outline: Buffer }}
  */
-function getPlaceholderIcons() {
-  const icon = Buffer.from(PLACEHOLDER_ICON_BASE64, 'base64');
-  return { color: icon, outline: icon };
+function resolvePackageIcons(runtimeValues) {
+  return getMicrosoftCopilotIcons({
+    colorPath: runtimeValues?.iconColorPath,
+    outlinePath: runtimeValues?.iconOutlinePath
+  });
 }
 
 /**
@@ -67,7 +75,8 @@ function renderCopilotTemplates(runtimeValues, renderTemplateFile, templatesDir)
       runtimeValues
     )
   };
-  const installText = renderTemplateFile(path.join(templatesDir, 'install.template.md.hbs'), runtimeValues);
+  // INSTALL prose + Entra SSO form table live in templates (partial entraSsoRegistration).
+  const installText = renderCopilotChannelTemplate('install.template.md.hbs', runtimeValues);
   return { sourceFiles, installText };
 }
 
@@ -112,6 +121,9 @@ function buildCopilotValidation(runtimeValues, paths, sourceFileNames) {
     runtimeMcpUrl: runtimeValues.mcpUrl,
     runtimeTransport: runtimeValues.runtimeTransport,
     expectedLayerBToolNames: runtimeValues.layerBToolNames || [],
+    governedToolNames: runtimeValues.layerBToolNames || [],
+    installReady: runtimeValues.installReady === true,
+    blocker: runtimeValues.discoveryBlocker || null,
     boundaries: {
       onePackagePerEnvironment: true,
       topLevelVendorToolsExposed: false,
@@ -142,6 +154,65 @@ function computeCopilotArtifactHash(parts) {
   return hash.digest('hex');
 }
 
+/**
+ * @param {Object} runtimeValues
+ * @returns {Object}
+ */
+function buildCopilotSummaryRuntime(runtimeValues) {
+  return {
+    runtimeSystemKey: runtimeValues.runtimeSystemKey,
+    remoteMcpUrl: runtimeValues.mcpUrl,
+    transport: runtimeValues.runtimeTransport,
+    assistantCatalogUrl: runtimeValues.assistantCatalogUrl,
+    roleAssistantResolution: 'dynamic-runtime',
+    layerBToolNames: runtimeValues.layerBToolNames || [],
+    governedToolNames: runtimeValues.layerBToolNames || []
+  };
+}
+
+/**
+ * @param {Object} runtimeValues
+ * @returns {Object}
+ */
+function buildCopilotSummaryAuthentication(runtimeValues) {
+  const discovery = runtimeValues.discoveryAuthentication || null;
+  const serialized = discovery ? JSON.stringify(discovery) : '';
+  if (/authorizationServerMetadataUrl":"[^"]+"/i.test(serialized)) {
+    throw new Error('Keycloak authorizationServerMetadata must not appear in Copilot package summary');
+  }
+  return {
+    mode: runtimeValues.runtimeAuthMode,
+    pluginAuthType: 'OAuthPluginVault',
+    oauthPluginVaultReferenceId: runtimeValues.oauthPluginVaultReferenceId || null,
+    recommendedCapability: discovery?.recommendedCapability || null,
+    entraIssuer: runtimeValues.entraIssuer || discovery?.issuer || null,
+    entraEnterpriseAppId: runtimeValues.entraEnterpriseAppId || null,
+    entraTenantId: runtimeValues.entraTenantId || null,
+    entraSsoClientId: runtimeValues.entraSsoClientId || null,
+    scopes: runtimeValues.scopes || [],
+    discovery,
+    note:
+      'Microsoft Entra SSO via OAuthPluginVault (Teams auth-config reference_id); ' +
+      'miso-controller performs exchange — package carries public specs only; no Fabrix OAuth secrets'
+  };
+}
+
+/**
+ * @param {Object} runtimeValues
+ * @param {Object} paths
+ * @returns {Object}
+ */
+function buildCopilotSummaryPackage(runtimeValues, paths) {
+  return {
+    appId: runtimeValues.packageAppId,
+    version: runtimeValues.packageVersion,
+    sourceFiles: ['manifest.json', 'declarativeAgent.json', 'ai-plugin.json', 'color.png', 'outline.png'],
+    zipFileName: paths.zipFileName,
+    installGuide: 'INSTALL.md',
+    validationFile: path.relative(paths.rootDir, paths.validationPath)
+  };
+}
+
 /**
  * @param {Object} runtimeValues
  * @param {Object} paths
@@ -156,27 +227,16 @@ function buildCopilotSummary(runtimeValues, paths, validation, artifactHash) {
     baseName: runtimeValues.baseName,
     description: runtimeValues.appDescription,
     environment: runtimeValues.environment,
-    runtime: {
-      runtimeSystemKey: runtimeValues.runtimeSystemKey,
-      remoteMcpUrl: runtimeValues.mcpUrl,
-      transport: runtimeValues.runtimeTransport,
-      assistantCatalogUrl: runtimeValues.assistantCatalogUrl,
-      roleAssistantResolution: 'dynamic-runtime',
-      layerBToolNames: runtimeValues.layerBToolNames || []
-    },
-    authentication: {
-      mode: runtimeValues.runtimeAuthMode,
-      credentialKey: runtimeValues.credentialKey,
-      credentialPortalUrl: runtimeValues.credentialPortalUrl,
-      scopes: runtimeValues.scopes || []
-    },
-    package: {
-      appId: runtimeValues.packageAppId,
-      version: runtimeValues.packageVersion,
-      sourceFiles: ['manifest.json', 'declarativeAgent.json', 'ai-plugin.json', 'color.png', 'outline.png'],
-      zipFileName: paths.zipFileName,
-      installGuide: path.relative(paths.rootDir, paths.installPath),
-      validationFile: path.relative(paths.rootDir, paths.validationPath)
+    runtime: buildCopilotSummaryRuntime(runtimeValues),
+    authentication: buildCopilotSummaryAuthentication(runtimeValues),
+    package: buildCopilotSummaryPackage(runtimeValues, paths),
+    installReady: runtimeValues.installReady === true,
+    blocker: runtimeValues.discoveryBlocker || null,
+    links: {
+      readme: paths.installPath,
+      zip: paths.zipPath,
+      filesRoot: paths.sourceDir,
+      validation: paths.validationPath
     },
     probeTiers: {
       builderValidated: true,
@@ -211,24 +271,21 @@ function writeCopilotArtifacts(params) {
   fs.writeFileSync(path.join(paths.sourceDir, 'outline.png'), icons.outline);
   fs.writeFileSync(paths.zipPath, zipBuffer);
   fs.writeFileSync(paths.installPath, installText, 'utf8');
+  if (paths.installReadmePath) {
+    fs.writeFileSync(paths.installReadmePath, installText, 'utf8');
+  }
   fs.writeFileSync(paths.validationPath, validationText, 'utf8');
   fs.writeFileSync(paths.summaryPath, summaryText, 'utf8');
 }
 
 /**
  * @param {Object} params
- * @param {Object} params.runtimeValues
- * @param {string} params.templatesDir
- * @param {string} params.outputPath
- * @param {boolean} [params.dryRun]
- * @param {(content: string) => void} params.assertNoSecretsInArtifact
- * @param {(templatePath: string, context: Object) => string} params.renderTemplateFile
- * @returns {{ outputPath: string, artifactHash: string, content: string, installPath: string }}
+ * @param {Object} runtimeValues
+ * @param {Object} paths
+ * @param {{ color: Buffer, outline: Buffer }} icons
+ * @returns {{ summary: Object, summaryText: string, zipBuffer: Buffer, sourceFiles: Object, installText: string, validationText: string }}
  */
-function generateMicrosoftCopilotPackage(params) {
-  const runtimeValues = params.runtimeValues || {};
-  const paths = buildCopilotOutputPaths(params.outputPath, runtimeValues);
-  const icons = getPlaceholderIcons();
+function buildCopilotPackagePayload(params, runtimeValues, paths, icons) {
   const { sourceFiles, installText } = renderCopilotTemplates(
     runtimeValues,
     params.renderTemplateFile,
@@ -236,6 +293,7 @@ function generateMicrosoftCopilotPackage(params) {
   );
   assertNoSecretsInSourceFiles(sourceFiles, params.assertNoSecretsInArtifact);
   params.assertNoSecretsInArtifact(installText);
+  assertValidMicrosoftCopilotPackage(sourceFiles, icons);
   const zipBuffer = buildCopilotZipBuffer(sourceFiles, icons);
   const validation = buildCopilotValidation(runtimeValues, paths, Object.keys(sourceFiles));
   const validationText = JSON.stringify(validation, null, 2);
@@ -250,22 +308,45 @@ function generateMicrosoftCopilotPackage(params) {
   const summary = buildCopilotSummary(runtimeValues, paths, validation, artifactHash);
   const summaryText = JSON.stringify(summary, null, 2);
   params.assertNoSecretsInArtifact(summaryText);
+  return { summary, summaryText, zipBuffer, sourceFiles, installText, validationText };
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} params.runtimeValues
+ * @param {string} params.templatesDir
+ * @param {string} params.outputPath
+ * @param {boolean} [params.dryRun]
+ * @param {(content: string) => void} params.assertNoSecretsInArtifact
+ * @param {(templatePath: string, context: Object) => string} params.renderTemplateFile
+ * @returns {{ outputPath: string, artifactHash: string, content: string, installPath: string }}
+ */
+function generateMicrosoftCopilotPackage(params) {
+  const runtimeValues = applyMicrosoftCopilotDisplayLimits({ ...(params.runtimeValues || {}) });
+  assertCopilotPackageOauthPluginVaultReference(runtimeValues);
+  const paths = buildCopilotOutputPaths(params.outputPath, runtimeValues);
+  const icons = resolvePackageIcons(runtimeValues);
+  const payload = buildCopilotPackagePayload(params, runtimeValues, paths, icons);
   if (!params.dryRun) {
     writeCopilotArtifacts({
       paths,
-      sourceFiles,
+      sourceFiles: payload.sourceFiles,
       icons,
-      zipBuffer,
-      installText,
-      validationText,
-      summaryText
+      zipBuffer: payload.zipBuffer,
+      installText: payload.installText,
+      validationText: payload.validationText,
+      summaryText: payload.summaryText
     });
   }
   return {
     outputPath: paths.summaryPath,
-    artifactHash,
-    content: summaryText,
-    installPath: paths.installPath
+    artifactHash: payload.summary.artifact.hash,
+    content: payload.summaryText,
+    installPath: paths.installPath,
+    zipPath: paths.zipPath,
+    links: payload.summary.links,
+    installReady: payload.summary.installReady === true,
+    blocker: payload.summary.blocker || null
   };
 }
 

package/lib/channels/microsoft-copilot-validate.js

@@ -0,0 +1,197 @@
+/**
+ * Validate Microsoft Copilot package source files before ZIP.
+ *
+ * @fileoverview Schema-oriented checks for Teams + declarative agent + AI plugin manifests
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const {
+  TEAMS_NAME_SHORT_MAX,
+  TEAMS_NAME_FULL_MAX,
+  TEAMS_DESCRIPTION_SHORT_MAX,
+  TEAMS_DESCRIPTION_FULL_MAX,
+  PLUGIN_NAME_FOR_HUMAN_MAX,
+  PLUGIN_DESCRIPTION_FOR_HUMAN_MAX
+} = require('./microsoft-copilot-limits');
+const { readPngDimensions } = require('./microsoft-copilot-icons');
+
+const ALLOWED_AUTH_TYPES = new Set(['None', 'OAuthPluginVault', 'ApiKeyPluginVault']);
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} max
+ * @param {string[]} errors
+ */
+function assertMaxLength(value, label, max, errors) {
+  if (typeof value !== 'string') {
+    errors.push(`${label} must be a string`);
+    return;
+  }
+  if (value.length > max) {
+    errors.push(`${label} exceeds ${max} characters (got ${value.length})`);
+  }
+}
+
+/**
+ * @param {Record<string, string>} sourceFiles
+ * @returns {{ manifest: Object|null, agent: Object|null, plugin: Object|null, errors: string[] }}
+ */
+function parsePackageJsonFiles(sourceFiles) {
+  const errors = [];
+  const parsed = { manifest: null, agent: null, plugin: null };
+  try {
+    parsed.manifest = JSON.parse(sourceFiles['manifest.json'] || '');
+  } catch {
+    errors.push('manifest.json is not valid JSON');
+  }
+  try {
+    parsed.agent = JSON.parse(sourceFiles['declarativeAgent.json'] || '');
+  } catch {
+    errors.push('declarativeAgent.json is not valid JSON');
+  }
+  try {
+    parsed.plugin = JSON.parse(sourceFiles['ai-plugin.json'] || '');
+  } catch {
+    errors.push('ai-plugin.json is not valid JSON');
+  }
+  return { ...parsed, errors };
+}
+
+/**
+ * @param {Object|null} manifest
+ * @param {string[]} errors
+ */
+function validateTeamsManifest(manifest, errors) {
+  if (!manifest) return;
+  assertMaxLength(manifest?.name?.short, 'manifest.name.short', TEAMS_NAME_SHORT_MAX, errors);
+  assertMaxLength(manifest?.name?.full, 'manifest.name.full', TEAMS_NAME_FULL_MAX, errors);
+  assertMaxLength(
+    manifest?.description?.short,
+    'manifest.description.short',
+    TEAMS_DESCRIPTION_SHORT_MAX,
+    errors
+  );
+  assertMaxLength(
+    manifest?.description?.full,
+    'manifest.description.full',
+    TEAMS_DESCRIPTION_FULL_MAX,
+    errors
+  );
+  if (!manifest.copilotAgents?.declarativeAgents?.length) {
+    errors.push('manifest.copilotAgents.declarativeAgents is required');
+  }
+}
+
+/**
+ * @param {Object|null} agent
+ * @param {string[]} errors
+ */
+function validateDeclarativeAgent(agent, errors) {
+  if (!agent) return;
+  if (agent.version !== 'v1.4') {
+    errors.push('declarativeAgent.version must be "v1.4"');
+  }
+  if (!agent.id || !agent.name || !agent.description || !agent.instructions) {
+    errors.push('declarativeAgent requires id, name, description, and instructions');
+  }
+}
+
+/**
+ * @param {Object|null} plugin
+ * @param {string[]} errors
+ */
+function validateAiPlugin(plugin, errors) {
+  if (!plugin) return;
+  if (plugin.schema_version !== 'v2.4') {
+    errors.push('ai-plugin.schema_version must be "v2.4"');
+  }
+  assertMaxLength(plugin.name_for_human, 'ai-plugin.name_for_human', PLUGIN_NAME_FOR_HUMAN_MAX, errors);
+  assertMaxLength(
+    plugin.description_for_human,
+    'ai-plugin.description_for_human',
+    PLUGIN_DESCRIPTION_FOR_HUMAN_MAX,
+    errors
+  );
+  if (!plugin.namespace || !/^[A-Za-z0-9-]+$/.test(plugin.namespace)) {
+    errors.push('ai-plugin.namespace is required (alphanumeric and hyphen only)');
+  }
+  validateAiPluginRuntime(plugin, errors);
+}
+
+/**
+ * @param {Object} plugin
+ * @param {string[]} errors
+ */
+function validateAiPluginRuntime(plugin, errors) {
+  const runtime = Array.isArray(plugin.runtimes) ? plugin.runtimes[0] : null;
+  if (!runtime || runtime.type !== 'RemoteMCPServer') {
+    errors.push('ai-plugin.runtimes[0].type must be RemoteMCPServer');
+    return;
+  }
+  if (!ALLOWED_AUTH_TYPES.has(runtime.auth?.type)) {
+    errors.push(
+      `ai-plugin.runtimes[0].auth.type must be one of ${[...ALLOWED_AUTH_TYPES].join(', ')}`
+    );
+  }
+  if (runtime.auth?.type === 'OAuthPluginVault') {
+    const ref = runtime.auth.reference_id;
+    if (typeof ref !== 'string' || !ref.trim()) {
+      errors.push(
+        'OAuthPluginVault.reference_id is required — pass --oauth-plugin-vault-reference-id ' +
+          'with the Teams Developer Portal Entra SSO auth-config id'
+      );
+    }
+  }
+  if (runtime.auth?.type === 'None') {
+    errors.push(
+      'ai-plugin.runtimes[0].auth.type None is not allowed; use OAuthPluginVault (Microsoft token / Entra)'
+    );
+  }
+  const desc = runtime.spec?.mcp_tool_description;
+  if (desc && (desc.mode || desc.layerBToolNames)) {
+    errors.push(
+      'ai-plugin mcp_tool_description must not use mode/layerBToolNames; omit for dynamic discovery or use tools/file'
+    );
+  }
+}
+
+/**
+ * @param {{ color: Buffer, outline: Buffer }} icons
+ * @param {string[]} errors
+ */
+function validatePackageIcons(icons, errors) {
+  const colorDims = readPngDimensions(icons.color);
+  const outlineDims = readPngDimensions(icons.outline);
+  if (!colorDims || colorDims.width !== 192 || colorDims.height !== 192) {
+    errors.push('color.png must be a 192x192 PNG');
+  }
+  if (!outlineDims || outlineDims.width !== 32 || outlineDims.height !== 32) {
+    errors.push('outline.png must be a 32x32 PNG');
+  }
+}
+
+/**
+ * @param {Record<string, string>} sourceFiles
+ * @param {{ color: Buffer, outline: Buffer }} icons
+ * @throws {Error}
+ */
+function assertValidMicrosoftCopilotPackage(sourceFiles, icons) {
+  const parsed = parsePackageJsonFiles(sourceFiles);
+  const errors = [...parsed.errors];
+  validateTeamsManifest(parsed.manifest, errors);
+  validateDeclarativeAgent(parsed.agent, errors);
+  validateAiPlugin(parsed.plugin, errors);
+  validatePackageIcons(icons, errors);
+  if (errors.length) {
+    throw new Error(`Microsoft Copilot package validation failed:\n- ${errors.join('\n- ')}`);
+  }
+}
+
+module.exports = {
+  assertValidMicrosoftCopilotPackage,
+  ALLOWED_AUTH_TYPES
+};

package/lib/cli/index.js

@@ -67,6 +67,8 @@ function setupCoreCliCommands(program) {
   setupChannelCommands(program);
   setupDatasourceCommands(program);
   setupManifestCommands(program);
+  const { setupIntegrationDefinitionCommands } = require('../commands/integration-definition');
+  setupIntegrationDefinitionCommands(program);
 }
 
 /**

package/lib/cli/infra-guided-footers.js

@@ -95,7 +95,7 @@ function logPlatformSetupDurationHint(scope = 'platform') {
   const line =
     scope === 'dataplane'
       ? 'Installation may take a few minutes. Authenticating and starting Dataplane — please wait.'
-      : 'Installation may take a few minutes. Keycloak, Miso Controller, and Dataplane are starting — please wait.';
+      : 'Installation may take a few minutes. Keycloak, Miso Controller, Dataplane, and Builder API are starting — please wait.';
   logger.log(chalk.yellow(`⚠ ${line}`));
 }
 

package/lib/cli/infra-guided-public-url-warn.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Consolidate deferred public-URL health warnings for guided install UX.
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+
+/**
+ * @param {string} message
+ * @returns {{ kind: 'dns'|'localhost', url: string }|null}
+ */
+function extractPublicUrlFromWarning(message) {
+  const text = String(message || '');
+  const dnsMatch = text.match(/Public URL was not verified \(DNS\):\s*(\S+)/);
+  if (dnsMatch) {
+    return { kind: 'dns', url: dnsMatch[1].replace(/\.$/, '') };
+  }
+  const match = text.match(/Public URL was not verified:\s*(\S+)/);
+  if (match) {
+    return { kind: 'localhost', url: match[1].replace(/\.$/, '') };
+  }
+  return null;
+}
+
+/**
+ * Print one consolidated public-URL warning (avoid N near-duplicate lines).
+ * @param {string[]} messages
+ */
+function flushDeferredPublicUrlWarnings(messages) {
+  const list = (messages || []).filter(Boolean);
+  if (list.length === 0) {
+    return;
+  }
+  const parsed = list.map(extractPublicUrlFromWarning).filter(Boolean);
+  if (parsed.length === 0) {
+    for (const message of list) {
+      logger.log(formatWarningLine(message));
+    }
+    return;
+  }
+  const urls = [...new Set(parsed.map((row) => row.url))];
+  const hasDns = parsed.some((row) => row.kind === 'dns');
+  const urlPart = urls.length === 1 ? urls[0] : urls.join(', ');
+  const detail = hasDns
+    ? 'Hostname DNS and/or Traefik routing/TLS could not be verified; health succeeded via localhost only.'
+    : 'Health checks succeeded via localhost only. Validate Traefik routing, TLS, and DNS.';
+  logger.log(formatWarningLine(`Public URL was not verified: ${urlPart}. ${detail}`));
+}
+
+module.exports = {
+  extractPublicUrlFromWarning,
+  flushDeferredPublicUrlWarnings
+};