@redpanda-data/docs-extensions-and-macros 5.11.1 → 5.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.11.1",
+  "version": "5.12.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -102,7 +102,8 @@
     "cli-utils",
     "tools",
     "docker-compose",
-    "mcp"
+    "mcp",
+    "docs-data/rpk-overrides.schema.json"
   ],
   "license": "ISC",
   "engines": {
@@ -149,8 +150,8 @@
     "yargs": "^17.7.2"
   },
   "devDependencies": {
-    "@antora/cli": "3.1.4",
-    "@antora/site-generator": "3.1.4",
+    "@antora/cli": "^3.1.15",
+    "@antora/site-generator": "^3.1.15",
     "@asciidoctor/core": "2.2.8",
     "@web/dev-server": "^0.2.5",
     "jest": "^29.7.0",

package/tools/property-extractor/cloud_config.py

@@ -500,10 +500,23 @@ def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> D
                 skipped_count += 1
                 continue
             
-            # Only process cluster, broker, and topic properties for cloud support
+            # Only cluster properties get cloud metadata.
+            #
+            # The two sections this data comes from -- customer_managed_configs
+            # and readonly_cluster_config -- describe the Cloud control plane's
+            # view of CLUSTER configuration, and contain nothing else: every one
+            # of their entries resolves to a cluster property, and no topic
+            # property appears anywhere in the install pack.
+            #
+            # Emitting cloud_supported: false for a topic or broker property
+            # therefore asserted something this source cannot know. Downstream
+            # that read as "a Cloud reader cannot set this", which is wrong for
+            # topic properties -- Cloud users set them routinely through the
+            # Kafka API and Console, a surface the control plane does not gate.
+            # Leave the fields absent instead, so absent means "no opinion" and
+            # false keeps its meaning of "the control plane forbids it".
             config_scope = prop_data.get('config_scope', '')
-            if config_scope not in ['cluster', 'broker', 'topic']:
-                # Skip node config properties and others without cloud relevance
+            if config_scope != 'cluster':
                 skipped_count += 1
                 continue
             

package/tools/redpanda-connect/report-delta.js

@@ -422,10 +422,50 @@ function buildComponentMap(indexObj) {
   return map;
 }
 
+/**
+ * Whether to refresh the Connect plugin before reading its version.
+ *
+ * Only ephemeral environments should: the refresh uses "install --force",
+ * which skips the safeguard that "upgrade" applies to a self-managed plugin
+ * (see the comment in getRpkConnectVersion), so on a real machine it can
+ * change which Connect binary the user runs afterwards.
+ *
+ * Defaults to on when CI is set. RPCN_FORCE_CONNECT_INSTALL overrides in
+ * either direction, for forcing a refresh locally or suppressing one in a
+ * CI-like environment that owns its own Connect installation.
+ */
+function shouldRefreshConnectPlugin() {
+  const override = process.env.RPCN_FORCE_CONNECT_INSTALL;
+  if (override !== undefined && override !== '') {
+    return !['0', 'false', 'no', 'off'].includes(override.toLowerCase());
+  }
+  return Boolean(process.env.CI);
+}
+
 function getRpkConnectVersion() {
   try {
-    // Make sure the connect plugin is upgraded first (silent)
-    execSync('rpk connect upgrade', { stdio: 'ignore' });
+    // Ensure the connect plugin is current (silent). Deliberately "install
+    // --force", not "upgrade": upgrade's version comparison parses the
+    // currently-installed version through a regex capped at two digits per
+    // segment (redpanda.VersionFromString in rpk/pkg/redpanda/version.go),
+    // which throws for any Connect version >= 4.100.0 — the same bug class
+    // as CON-529, in a different function that its fix didn't touch. Fixed
+    // upstream on dev (redpanda commit 8fc022e7) but present in all rpk
+    // releases up to at least v26.2.1; keep this workaround until a fixed
+    // rpk release ships. install's "latest" path (the default) skips that
+    // regex entirely, so it isn't exposed to the bug.
+    //
+    // The trade-off is that "install --force" drops a safeguard "upgrade"
+    // keeps: upgrade refuses to touch a plugin whose Managed flag is false
+    // (rpk/pkg/cli/connect/upgrade.go), which is how a Connect installed by
+    // Homebrew or by hand is protected. A forced install instead writes a
+    // managed binary into the plugin dir that rpk prioritises, shadowing
+    // that installation for every later rpk call. So refresh only where the
+    // Connect installation is disposable, and leave a developer's machine
+    // exactly as it is — reporting the version already installed there.
+    if (shouldRefreshConnectPlugin()) {
+      execSync('rpk connect install --force', { stdio: 'ignore' });
+    }
 
     // Now capture the --version output
     const raw = execSync('rpk connect --version', {
@@ -444,7 +484,13 @@ function getRpkConnectVersion() {
     }
     return match[1];
   } catch (err) {
-    throw new Error(`Unable to run "rpk connect --version": ${err.message}`);
+    // Outside CI the plugin is never installed on the caller's behalf, so say
+    // how to get one rather than only reporting that the call failed.
+    const hint = shouldRefreshConnectPlugin()
+      ? ''
+      : ' If Redpanda Connect is not installed, run "rpk connect install" first,' +
+        ' or set RPCN_FORCE_CONNECT_INSTALL=1 to let this command install it.';
+    throw new Error(`Unable to run "rpk connect --version": ${err.message}${hint}`);
   }
 }
 

package/tools/rpk-docs/extract-conditional-content.js

@@ -11,7 +11,9 @@ const { spawnSync } = require('child_process')
 
 const docsDir = process.argv[2] || '../docs'
 const rpkDir = path.join(docsDir, 'modules/reference/pages/rpk')
-const overridesPath = path.join(__dirname, '../../docs-data/rpk-overrides.json')
+// The canonical overrides live in the docs repo (the docsDir this script
+// already takes); this repo ships only the schema.
+const overridesPath = process.argv[3] || path.join(docsDir, 'docs-data/rpk-overrides.json')
 
 // Validate docsDir exists and is a directory
 if (!fs.existsSync(docsDir) || !fs.statSync(docsDir).isDirectory()) {