@aifabrix/builder 2.52.0 → 2.53.0

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

@@ -9,12 +9,19 @@
 '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,
+  applyWebApplicationInfoFields
+} = require('./microsoft-copilot-entra-sso-form');
 
 /**
  * @param {string} outputPath
@@ -37,16 +44,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
+  });
 }
 
 /**
@@ -65,9 +76,11 @@ function renderCopilotTemplates(runtimeValues, renderTemplateFile, templatesDir)
     'ai-plugin.json': renderTemplateFile(
       path.join(templatesDir, 'ai-plugin.template.json.hbs'),
       runtimeValues
-    )
+    ),
+    'fi-fi.json': renderTemplateFile(path.join(templatesDir, 'fi-fi.template.json.hbs'), 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 };
 }
 
@@ -91,6 +104,7 @@ function buildCopilotZipBuffer(sourceFiles, icons) {
   zip.addFile('manifest.json', Buffer.from(sourceFiles['manifest.json'], 'utf8'));
   zip.addFile('declarativeAgent.json', Buffer.from(sourceFiles['declarativeAgent.json'], 'utf8'));
   zip.addFile('ai-plugin.json', Buffer.from(sourceFiles['ai-plugin.json'], 'utf8'));
+  zip.addFile('fi-fi.json', Buffer.from(sourceFiles['fi-fi.json'], 'utf8'));
   zip.addFile('color.png', icons.color);
   zip.addFile('outline.png', icons.outline);
   return zip.toBuffer();
@@ -112,14 +126,18 @@ 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,
       roleAssistantResolution: 'dynamic-runtime'
     },
     requiresMicrosoftAdmin: [
-      'upload-package',
-      'tenant-approval',
+      'developer-portal-import',
+      'publish-to-org',
+      'teams-admin-approval',
       'assignment-and-consent',
       'first-copilot-invoke'
     ]
@@ -142,6 +160,72 @@ 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',
+      'fi-fi.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 +240,19 @@ 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,
+    packageReady: runtimeValues.packageReady !== false && runtimeValues.installReady === true,
+    packageBlocker: runtimeValues.packageBlocker || runtimeValues.discoveryBlocker || null,
+    microsoftPublicationPending: runtimeValues.microsoftPublicationPending !== false,
+    links: {
+      readme: paths.installPath,
+      zip: paths.zipPath,
+      filesRoot: paths.sourceDir,
+      validation: paths.validationPath
     },
     probeTiers: {
       builderValidated: true,
@@ -207,28 +283,26 @@ function writeCopilotArtifacts(params) {
     'utf8'
   );
   fs.writeFileSync(path.join(paths.sourceDir, 'ai-plugin.json'), sourceFiles['ai-plugin.json'], 'utf8');
+  fs.writeFileSync(path.join(paths.sourceDir, 'fi-fi.json'), sourceFiles['fi-fi.json'], 'utf8');
   fs.writeFileSync(path.join(paths.sourceDir, 'color.png'), icons.color);
   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 +310,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);
@@ -243,6 +318,7 @@ function generateMicrosoftCopilotPackage(params) {
     sourceFiles['manifest.json'],
     sourceFiles['declarativeAgent.json'],
     sourceFiles['ai-plugin.json'],
+    sourceFiles['fi-fi.json'],
     installText,
     validationText,
     zipBuffer
@@ -250,22 +326,72 @@ 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 };
+}
+
+/**
+ * Read prior webApplicationInfo from an existing source manifest (preserve on regenerate).
+ * @param {string} sourceDir
+ * @returns {{ id: string, resource: string }|null}
+ */
+function readPriorWebApplicationInfo(sourceDir) {
+  const manifestPath = path.join(sourceDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const info = parsed && parsed.webApplicationInfo;
+    if (
+      info &&
+      typeof info.id === 'string' &&
+      info.id.trim() &&
+      typeof info.resource === 'string' &&
+      info.resource.trim()
+    ) {
+      return { id: info.id.trim(), resource: info.resource.trim() };
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function generateMicrosoftCopilotPackage(params) {
+  const runtimeValues = applyMicrosoftCopilotDisplayLimits({ ...(params.runtimeValues || {}) });
+  assertCopilotPackageOauthPluginVaultReference(runtimeValues);
+  const paths = buildCopilotOutputPaths(params.outputPath, runtimeValues);
+  const prior = readPriorWebApplicationInfo(paths.sourceDir);
+  applyWebApplicationInfoFields(runtimeValues, {
+    webApplicationInfoId: runtimeValues.webApplicationInfoId,
+    webApplicationInfoResource: runtimeValues.webApplicationInfoResource,
+    priorWebApplicationInfo: prior
+  });
+  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,
+    packageReady: payload.summary.packageReady === true,
+    packageBlocker: payload.summary.packageBlocker || null,
+    microsoftPublicationPending: payload.summary.microsoftPublicationPending !== false
   };
 }
 

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

@@ -0,0 +1,227 @@
+/**
+ * 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} runtime
+ * @param {string[]} errors
+ */
+function validateAiPluginAuth(runtime, errors) {
+  const authType = runtime.auth?.type;
+  if (!ALLOWED_AUTH_TYPES.has(authType)) {
+    errors.push(
+      `ai-plugin.runtimes[0].auth.type must be one of ${[...ALLOWED_AUTH_TYPES].join(', ')}`
+    );
+  }
+  if (authType === '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 (authType === 'None') {
+    errors.push(
+      'ai-plugin.runtimes[0].auth.type None is not allowed; use OAuthPluginVault (Microsoft token / Entra)'
+    );
+  }
+}
+
+/**
+ * @param {Object} plugin
+ * @param {Object} runtime
+ * @param {string[]} errors
+ */
+function validateAiPluginDiscovery(plugin, runtime, errors) {
+  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'
+    );
+  }
+  if (!Array.isArray(plugin.functions) || plugin.functions.length !== 0) {
+    errors.push(
+      'ai-plugin.functions must be [] for Microsoft dynamic MCP tool discovery ' +
+        '(see run_for_functions ["*"])'
+    );
+  }
+  const runFor = runtime.run_for_functions;
+  if (!Array.isArray(runFor) || runFor.length !== 1 || runFor[0] !== '*') {
+    errors.push(
+      'ai-plugin.runtimes[0].run_for_functions must be ["*"] for dynamic MCP tool discovery'
+    );
+  }
+}
+
+/**
+ * @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;
+  }
+  validateAiPluginAuth(runtime, errors);
+  validateAiPluginDiscovery(plugin, runtime, errors);
+}
+
+/**
+ * @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/attach-default-help-examples.js

@@ -0,0 +1,102 @@
+/**
+ * Attach minimal product-neutral Examples: blocks to commands that lack them.
+ * Runs after setupCommands so intentional addHelpText Examples are preserved.
+ *
+ * @fileoverview Default CLI help Examples for check:cli-help gate
+ */
+
+'use strict';
+
+const EXAMPLE_HEADER_RE = /Examples:/m;
+const EXAMPLE_LINE_RE = /\$ aifabrix |\$ af /;
+
+/**
+ * @param {import('commander').Command} cmd
+ * @returns {string}
+ */
+function captureHelpOutput(cmd) {
+  if (!cmd || typeof cmd.outputHelp !== 'function') {
+    return '';
+  }
+  let buf = '';
+  cmd.outputHelp({
+    write: (chunk) => {
+      buf += String(chunk);
+    }
+  });
+  return buf;
+}
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+function hasValidExamples(text) {
+  return EXAMPLE_HEADER_RE.test(text) && EXAMPLE_LINE_RE.test(text);
+}
+
+/**
+ * @param {string} pathStr
+ * @returns {string}
+ */
+function defaultExamplesBlock(pathStr) {
+  return `
+Examples:
+  $ aifabrix ${pathStr}
+  $ aifabrix ${pathStr} -h
+`;
+}
+
+/**
+ * @param {import('commander').Command} cmd
+ * @param {string[]} parts
+ * @param {Array<{ cmd: import('commander').Command, path: string }>} out
+ */
+function collectCommands(cmd, parts, out) {
+  // Tests sometimes pass mock nodes without Commander methods — skip those.
+  if (!cmd || typeof cmd.name !== 'function') {
+    return;
+  }
+  const name = cmd.name();
+  if (name === 'help') {
+    return;
+  }
+  const next = name && name !== 'aifabrix' ? parts.concat(name) : parts;
+  const subs = Array.isArray(cmd.commands) ? cmd.commands : [];
+  if (next.length > 0) {
+    out.push({ cmd, path: next.join(' ') });
+  }
+  for (const child of subs) {
+    collectCommands(child, next, out);
+  }
+}
+
+/**
+ * Ensure every leaf and parent has Examples with $ aifabrix / $ af.
+ * @param {import('commander').Command} program
+ * @returns {number} count of commands that received a default Examples block
+ */
+function attachDefaultHelpExamples(program) {
+  const entries = [];
+  collectCommands(program, [], entries);
+  let attached = 0;
+  for (const { cmd, path: pathStr } of entries) {
+    if (typeof cmd.addHelpText !== 'function') {
+      continue;
+    }
+    const text = captureHelpOutput(cmd);
+    if (hasValidExamples(text)) {
+      continue;
+    }
+    cmd.addHelpText('after', defaultExamplesBlock(pathStr));
+    attached += 1;
+  }
+  return attached;
+}
+
+module.exports = {
+  attachDefaultHelpExamples,
+  hasValidExamples,
+  captureHelpOutput,
+  defaultExamplesBlock
+};

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);
 }
 
 /**
@@ -98,6 +100,8 @@ function setupCommands(program) {
   setupCoreCliCommands(program);
   setupExtendedCliCommands(program);
   setupDevAndPlatformCommands(program);
+  const { attachDefaultHelpExamples } = require('./attach-default-help-examples');
+  attachDefaultHelpExamples(program);
 }
 
 module.exports = {