Fix Redpanda Connect cloud-only connector automation (#163)

JakeSCahill · github-actions[bot] · web-flow · commit 014729d93f69 · 2026-01-06T15:33:13.000Z
* Fix Redpanda Connect cloud-only connector automation * docs: Auto-update CLI reference documentation (PR #163) --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
diff --git a/CLI_REFERENCE.adoc b/CLI_REFERENCE.adoc
@@ -1074,7 +1074,7 @@ Branch name for in-progress content
 Repository URL (default: "https://github.com/redpanda-data/redpanda.git")
 
 `-s, --surface <surface>`::
-Which API surface(s) to bundle (choices: "admin", "connect", "both")
+Which API surfaces to bundle (choices: "admin", "connect", "both")
 
 `--out-admin <path>`::
 Output path for admin API (default: "admin/redpanda-admin-api.yaml")
diff --git a/__tests__/tools/cgo-detection.test.js b/__tests__/tools/cgo-detection.test.js
@@ -393,7 +393,7 @@ async function runTests() {
       results.tests.filter(t => !t.passed).forEach(t => {
         console.error(`  - ${t.name}: ${t.details}`);
       });
-      throw new Error(`${results.failed} test(s) failed`);
+      throw new Error(`${results.failed} tests failed`);
     }
 
     console.log('✅ All tests passed!\n');
diff --git a/bin/doc-tools-mcp.js b/bin/doc-tools-mcp.js
@@ -362,7 +362,7 @@ const tools = [
         },
         surface: {
           type: 'string',
-          description: 'Which API surface(s) to bundle (optional, defaults to "both")',
+          description: 'Which API surfaces to bundle (optional, defaults to "both")',
           enum: ['admin', 'connect', 'both']
         },
         out_admin: {
diff --git a/bin/doc-tools.js b/bin/doc-tools.js
@@ -1630,7 +1630,7 @@ automation
   .option('-t, --tag <tag>', 'Git tag for released content')
   .option('-b, --branch <branch>', 'Branch name for in-progress content')
   .option('--repo <url>', 'Repository URL', 'https://github.com/redpanda-data/redpanda.git')
-  .addOption(new Option('-s, --surface <surface>', 'Which API surface(s) to bundle').choices(['admin', 'connect', 'both']).makeOptionMandatory())
+  .addOption(new Option('-s, --surface <surface>', 'Which API surfaces to bundle').choices(['admin', 'connect', 'both']).makeOptionMandatory())
   .option('--out-admin <path>', 'Output path for admin API', 'admin/redpanda-admin-api.yaml')
   .option('--out-connect <path>', 'Output path for connect API', 'connect/redpanda-connect-api.yaml')
   .option('--admin-major <string>', 'Admin API major version', 'v2.0.0')
diff --git a/bin/mcp-tools/generated-docs-review.js b/bin/mcp-tools/generated-docs-review.js
@@ -306,10 +306,10 @@ function generateReviewReport(results, outputPath) {
   // Next steps
   report += `== Next Steps\n\n`;
   if (errorIssues.length > 0) {
-    report += `. *Fix errors first* - Address the ${errorIssues.length} error(s) above\n`;
+    report += `. *Fix errors first* - Address the ${errorIssues.length} errors above\n`;
   }
   if (warningIssues.length > 0) {
-    report += `${errorIssues.length > 0 ? '. ' : '. '}*Review warnings* - Prioritize the ${warningIssues.length} warning(s)\n`;
+    report += `${errorIssues.length > 0 ? '. ' : '. '}*Review warnings* - Prioritize the ${warningIssues.length} warnings\n`;
   }
   const step = errorIssues.length > 0 && warningIssues.length > 0 ? 3 : errorIssues.length > 0 || warningIssues.length > 0 ? 2 : 1;
   report += `${step > 1 ? '. ' : '. '}*Regenerate documentation* - After making changes, regenerate the docs\n`;
diff --git a/bin/mcp-tools/mcp-validation.js b/bin/mcp-tools/mcp-validation.js
@@ -250,7 +250,7 @@ function formatValidationResults(results, config) {
     lines.push('✓ Validation passed');
   } else {
     lines.push('✗ Validation failed');
-    lines.push(`  ${results.errors.length} error(s) must be fixed`);
+    lines.push(`  ${results.errors.length} errors must be fixed`);
   }
 
   return lines.join('\n');
diff --git a/bin/mcp-tools/openapi.js b/bin/mcp-tools/openapi.js
@@ -16,7 +16,7 @@ const { getAntoraStructure } = require('./antora');
  * @param {string} [args.tag] - Git tag for released content (for example, "v24.3.2" or "24.3.2")
  * @param {string} [args.branch] - Branch name for in-progress content (for example, "dev", "main")
  * @param {string} [args.repo] - Repository URL
- * @param {string} [args.surface] - Which API surface(s) to bundle: 'admin', 'connect', or 'both'
+ * @param {string} [args.surface] - Which API surfaces to bundle: 'admin', 'connect', or 'both'
  * @param {string} [args.out_admin] - Output path for admin API
  * @param {string} [args.out_connect] - Output path for connect API
  * @param {string} [args.admin_major] - Admin API major version
@@ -155,7 +155,7 @@ function generateBundleOpenApi(args) {
       surface,
       files_generated: filesGenerated,
       output: output.trim(),
-      summary: `Bundled OpenAPI documentation for ${surface} API(s) at ${refType} ${version}`
+      summary: `Bundled OpenAPI documentation for ${surface} APIs at ${refType} ${version}`
     };
   } catch (err) {
     return {
diff --git a/extensions/generate-rp-connect-categories.js b/extensions/generate-rp-connect-categories.js
@@ -73,7 +73,6 @@ module.exports.register = function ({ config }) {
         const status = attrs.status || extractAttribute(file, 'status')
         const driverSupport = attrs['driver-support'] || extractAttribute(file, 'driver-support')
         const cacheSupport = attrs['cache-support'] || extractAttribute(file, 'cache-support')
-        // FIXED: Use correct attribute name (page-commercial-names, not commercial-names)
         const commercialNames = attrs['page-commercial-names'] || extractAttribute(file, 'page-commercial-names')
 
         const pubUrl = file.pub.url
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.13.2",
+  "version": "4.13.3",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
diff --git a/tools/bundle-openapi.js b/tools/bundle-openapi.js
@@ -551,7 +551,7 @@ function postProcessBundle(filePath, options, quiet = false) {
 }
 
 /**
- * Bundle OpenAPI fragments for the specified API surface(s) from a repository tag and write the resulting bundled YAML files to disk.
+ * Bundle OpenAPI fragments for the specified API surfaces from a repository tag and write the resulting bundled YAML files to disk.
  *
  * @param {Object} options - Configuration options.
  * @param {string} options.tag - Git tag to checkout (for example, 'v25.1.1').
diff --git a/tools/redpanda-connect/README.adoc b/tools/redpanda-connect/README.adoc
@@ -665,13 +665,13 @@ Connectors can have human-friendly commercial names that appear in catalogs and
 ----
 = kafka_franz
 :type: input
-:commercial-names: Franz-go, Apache Kafka
+:page-commercial-names: Franz-go, Apache Kafka
 :categories: ["Services"]
 ----
 
 The `generate-rp-connect-categories` extension reads these commercial names and uses the first one as the primary display name. If multiple names are provided (comma-separated), only the first is used for display.
 
-*Default behavior:* If no `:commercial-names:` attribute is found, the connector key name is used (e.g., `kafka_franz`).
+*Default behavior:* If no `:page-commercial-names:` attribute is found, the connector key name is used (such as `kafka_franz`).
 
 *Adding commercial names to new connectors:*
 
@@ -681,12 +681,12 @@ When generating documentation for new connectors with `--draft-missing`, writers
 ----
 ### ✍️ Writer Action Required
 
-For each new connector, please add the `:commercial-names:` attribute to the frontmatter:
+For each new connector, please add the `:page-commercial-names:` attribute to the frontmatter:
 
 ```asciidoc
 = Connector Name
 :type: input
-:commercial-names: Commercial Name, Alternative Name
+:page-commercial-names: Commercial Name, Alternative Name
 ```
 
 _This helps improve discoverability and ensures proper categorization._
diff --git a/tools/redpanda-connect/connector-binary-analyzer.js b/tools/redpanda-connect/connector-binary-analyzer.js
@@ -503,7 +503,7 @@ async function analyzeAllBinaries(ossVersion, cloudVersion = null, dataDir = nul
       // These are connectors that require cgo-enabled builds
       cgoOnly = findCgoOnlyConnectors(ossIndex, cgoIndex);
 
-      console.log(`Done: Cgo analysis complete: ${cgoOnly.length} cgo-only connector(s) found`);
+      console.log(`Done: Cgo analysis complete: ${cgoOnly.length} cgo-only connectors found`);
       if (cgoOnly.length > 0) {
         console.log('   cgo-only connectors:');
         cgoOnly.forEach(c => console.log(`   • ${c.type}/${c.name} (${c.status})`));
diff --git a/tools/redpanda-connect/pr-summary-formatter.js b/tools/redpanda-connect/pr-summary-formatter.js
@@ -30,7 +30,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
 
   // High-level stats
   const stats = diffData.summary;
-  const hasChanges = Object.values(stats).some(v => v > 0);
+  const hasChanges = Object.values(stats).some(v => v > 0) || (draftedConnectors && draftedConnectors.length > 0);
 
   if (!hasChanges) {
     lines.push('✅ **No changes detected** - Documentation is up to date');
@@ -91,16 +91,78 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   if (stats.newComponents > 0) {
     lines.push('### ✍️ Writer Action Required');
     lines.push('');
-    lines.push('For each new connector, please add the `:commercial-names:` attribute to the frontmatter:');
+    lines.push('For each new connector, add the `:page-commercial-names:` attribute to the frontmatter:');
     lines.push('');
     lines.push('```asciidoc');
     lines.push('= Connector Name');
     lines.push(':type: input');
-    lines.push(':commercial-names: Commercial Name, Alternative Name');
+    lines.push(':page-commercial-names: Commercial Name, Alternative Name');
     lines.push('```');
     lines.push('');
     lines.push('_This helps improve discoverability and ensures proper categorization._');
     lines.push('');
+
+    // Check if any new connectors are cloud-supported
+    if (binaryAnalysis && binaryAnalysis.comparison) {
+      const newConnectorKeys = diffData.details.newComponents.map(c => ({
+        key: `${c.type}:${c.name}`,
+        type: c.type,
+        name: c.name
+      }));
+
+      const cloudSupported = newConnectorKeys.filter(item => {
+        // Check both inCloud (OSS+Cloud) and cloudOnly (Cloud-only)
+        const inCloud = binaryAnalysis.comparison.inCloud.some(c => `${c.type}:${c.name}` === item.key);
+        const cloudOnly = binaryAnalysis.comparison.cloudOnly &&
+          binaryAnalysis.comparison.cloudOnly.some(c => `${c.type}:${c.name}` === item.key);
+        return inCloud || cloudOnly;
+      });
+
+      if (cloudSupported.length > 0) {
+        lines.push('### ☁️ Cloud Docs Update Required');
+        lines.push('');
+        lines.push(`**${cloudSupported.length}** new connector${cloudSupported.length !== 1 ? 's are' : ' is'} available in Redpanda Cloud.`);
+        lines.push('');
+        lines.push('**Action:** Submit a separate PR to https://github.com/redpanda-data/cloud-docs to add the connector pages using include syntax:');
+        lines.push('');
+
+        // Check if any are cloud-only (need partial syntax)
+        const cloudOnly = cloudSupported.filter(item =>
+          binaryAnalysis.comparison.cloudOnly &&
+          binaryAnalysis.comparison.cloudOnly.some(c => `${c.type}:${c.name}` === item.key)
+        );
+        const regularCloud = cloudSupported.filter(item =>
+          !binaryAnalysis.comparison.cloudOnly ||
+          !binaryAnalysis.comparison.cloudOnly.some(c => `${c.type}:${c.name}` === item.key)
+        );
+
+        if (regularCloud.length > 0) {
+          lines.push('**For connectors in pages:**');
+          lines.push('```asciidoc');
+          lines.push('= Connector Name');
+          lines.push('');
+          lines.push('include::redpanda-connect:components:page$type/connector-name.adoc[tag=single-source]');
+          lines.push('```');
+          lines.push('');
+        }
+
+        if (cloudOnly.length > 0) {
+          lines.push('**For cloud-only connectors (in partials):**');
+          lines.push('```asciidoc');
+          lines.push('= Connector Name');
+          lines.push('');
+          lines.push('include::redpanda-connect:components:partial$components/cloud-only/type/connector-name.adoc[tag=single-source]');
+          lines.push('```');
+          lines.push('');
+        }
+
+        // Add instruction to update cloud whats-new
+        lines.push('**Also update the cloud whats-new file:**');
+        lines.push('');
+        lines.push('Add entries for the new cloud-supported connectors to the Redpanda Cloud whats-new file in the cloud-docs repository.');
+        lines.push('');
+      }
+    }
   }
 
   // Breaking Changes Section
diff --git a/tools/redpanda-connect/report-delta.js b/tools/redpanda-connect/report-delta.js
@@ -250,6 +250,7 @@ function generateConnectorDiffJson(oldIndex, newIndex, opts = {}) {
     result.binaryAnalysis.details = {
       cloudSupported: ba.comparison?.inCloud?.map(c => ({ type: c.type, name: c.name, status: c.status })) || [],
       selfHostedOnly: ba.comparison?.notInCloud?.map(c => ({ type: c.type, name: c.name, status: c.status })) || [],
+      cloudOnly: ba.comparison?.cloudOnly?.map(c => ({ type: c.type, name: c.name, status: c.status })) || [],
       cgoOnly: ba.cgoOnly?.map(c => ({ type: c.type, name: c.name, status: c.status })) || []
     };
   }
diff --git a/tools/redpanda-connect/rpcn-connector-docs-handler.js b/tools/redpanda-connect/rpcn-connector-docs-handler.js
diff --git a/tools/redpanda-connect/update-nav.js b/tools/redpanda-connect/update-nav.js

Original file line number	Diff line number	Diff line change
`@@ -393,7 +393,7 @@ async function runTests() {`
`393`	`393`	`results.tests.filter(t => !t.passed).forEach(t => {`
`394`	`394`	console.error(` - ${t.name}: ${t.details}`);
`395`	`395`	`});`
`396`		- throw new Error(`${results.failed} test(s) failed`);
	`396`	+ throw new Error(`${results.failed} tests failed`);
`397`	`397`	`}`
`398`	`398`
`399`	`399`	`console.log('✅ All tests passed!\n');`
Original file line number	Diff line number	Diff line change
`@@ -306,10 +306,10 @@ function generateReviewReport(results, outputPath) {`
`306`	`306`	`// Next steps`
`307`	`307`	report += `== Next Steps\n\n`;
`308`	`308`	`if (errorIssues.length > 0) {`
`309`		- report += `. Fix errors first - Address the ${errorIssues.length} error(s) above\n`;
	`309`	+ report += `. Fix errors first - Address the ${errorIssues.length} errors above\n`;
`310`	`310`	`}`
`311`	`311`	`if (warningIssues.length > 0) {`
`312`		- report += `${errorIssues.length > 0 ? '. ' : '. '}Review warnings - Prioritize the ${warningIssues.length} warning(s)\n`;
	`312`	+ report += `${errorIssues.length > 0 ? '. ' : '. '}Review warnings - Prioritize the ${warningIssues.length} warnings\n`;
`313`	`313`	`}`
`314`	`314`	`const step = errorIssues.length > 0 && warningIssues.length > 0 ? 3 : errorIssues.length > 0 \|\| warningIssues.length > 0 ? 2 : 1;`
`315`	`315`	report += `${step > 1 ? '. ' : '. '}Regenerate documentation - After making changes, regenerate the docs\n`;
Original file line number	Diff line number	Diff line change
`@@ -250,7 +250,7 @@ function formatValidationResults(results, config) {`
`250`	`250`	`lines.push('✓ Validation passed');`
`251`	`251`	`} else {`
`252`	`252`	`lines.push('✗ Validation failed');`
`253`		- lines.push(` ${results.errors.length} error(s) must be fixed`);
	`253`	+ lines.push(` ${results.errors.length} errors must be fixed`);
`254`	`254`	`}`
`255`	`255`
`256`	`256`	`return lines.join('\n');`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@redpanda-data/docs-extensions-and-macros",`
`3`		`- "version": "4.13.2",`
	`3`	`+ "version": "4.13.3",`
`4`	`4`	`"description": "Antora extensions and macros developed for Redpanda documentation.",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"antora",`