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

package/mcp/USER_GUIDE.adoc

@@ -1202,7 +1202,7 @@ claude mcp add --transport stdio --scope user redpanda-docs-tool-assistant -- \
 [,bash]
 ----
 claude mcp add --transport stdio --scope user redpanda-docs-tool-assistant -- \
-  npx -y doc-tools-mcp
+  npx -y --package=@redpanda-data/docs-extensions-and-macros doc-tools-mcp
 ----
 
 This adds the MCP server configuration to `~/.claude.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -24,6 +24,7 @@
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
     "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
     "test": "jest",
+    "test:unit": "jest --config jest.unit.config.js",
     "test:e2e": "jest __tests__/e2e/",
     "test:mcp": "jest __tests__/mcp/",
     "test:mcp:integration": "jest __tests__/mcp/integration.test.js",
@@ -101,7 +102,8 @@
     "cli-utils",
     "tools",
     "docker-compose",
-    "mcp"
+    "mcp",
+    "docs-data/rpk-overrides.schema.json"
   ],
   "license": "ISC",
   "engines": {
@@ -148,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/enterprise-features/parsers.js

@@ -112,23 +112,9 @@ function parseDisableTable (source) {
   return rows
 }
 
-/**
- * Extract the enterprise-components attribute list from rp-connect-docs
- * antora.yml, without a YAML dependency on the full file structure.
- *
- * @param {object} antoraConfig - Parsed antora.yml object.
- * @returns {string[]|undefined} The list, or undefined when absent.
- */
-function extractAntoraEnterpriseComponents (antoraConfig) {
-  const attributes = antoraConfig && antoraConfig.asciidoc && antoraConfig.asciidoc.attributes
-  const list = attributes && attributes['enterprise-components']
-  return Array.isArray(list) ? list.map(String) : undefined
-}
-
 module.exports = {
   parseCoreEnum,
   parseEnterpriseProperties,
   parseConnectEnterprisePlugins,
   parseDisableTable,
-  extractAntoraEnterpriseComponents,
 }

package/tools/enterprise-features/verify.js

@@ -122,22 +122,36 @@ function checkCoreProperties (features, enterpriseProperties, allPropertyNames)
 }
 
 /**
- * Compare connect info.csv enterprise plugins against the stale
- * enterprise-components list in rp-connect-docs antora.yml (when given).
+ * Validate registry connect-plugin pointers against the enterprise plugins
+ * in connect's info.csv.
+ *
+ * This used to diff info.csv against the hand-maintained
+ * enterprise-components list in rp-connect-docs antora.yml, but
+ * rp-connect-docs#485 removed that list (it had gone stale — the exact drift
+ * this validator exists to catch). Per-plugin enterprise status in the docs
+ * now comes from the generated connector catalog, which is built from the
+ * same connect metadata as info.csv, so it cannot drift by construction.
+ * What can still go stale is the registry itself: any entry that pins a
+ * specific plugin via `source: {kind: connect-plugin}` must name a plugin
+ * that info.csv actually marks enterprise.
+ *
+ * The check also reports what it verified, so a run with zero pinned
+ * plugins is visibly a shallow pass rather than a silent one.
  */
-function checkConnect (infoCsvPlugins, antoraList) {
+function checkConnect (infoCsvPlugins, features, connectRef) {
   const findings = []
-  if (!antoraList) return findings
-  for (const plugin of infoCsvPlugins) {
-    if (!antoraList.includes(plugin)) {
-      findings.push(finding('error', 'connect-list', `Plugin '${plugin}' is enterprise in info.csv but missing from the enterprise-components list in rp-connect-docs antora.yml.`))
-    }
-  }
-  for (const plugin of antoraList) {
-    if (!infoCsvPlugins.includes(plugin)) {
-      findings.push(finding('error', 'connect-list', `Plugin '${plugin}' is in the enterprise-components list in rp-connect-docs antora.yml but not enterprise in info.csv.`))
+  const pinned = []
+  const source = connectRef ? `info.csv@${connectRef}` : 'info.csv'
+  for (const feature of features) {
+    if (feature.source && feature.source.kind === 'connect-plugin') {
+      const value = String(feature.source.value).trim()
+      pinned.push(value)
+      if (!infoCsvPlugins.includes(value)) {
+        findings.push(finding('error', 'connect-list', `'${feature.name}' points at connect plugin '${value}', which is not an enterprise plugin in ${source} (renamed, removed, or no longer enterprise).`))
+      }
     }
   }
+  findings.push(finding('info', 'connect-list', `${source} lists ${infoCsvPlugins.length} enterprise plugin(s); ${pinned.length} pinned by registry connect-plugin entries. Individual plugins are documented by the generated connector catalog; the licensing table covers them through the aggregate connect-scope entries.`))
   return findings
 }
 
@@ -200,7 +214,7 @@ function buildMappingPartial (features, enumValues) {
  * @param {string} [sources.coreHeader] - enterprise_features.h contents.
  * @param {string} [sources.configurationHeader] - configuration.h contents.
  * @param {string} [sources.infoCsv] - connect info.csv contents.
- * @param {string[]} [sources.antoraEnterpriseComponents]
+ * @param {string} [sources.connectRef] - ref the info.csv was fetched at, for messages.
  * @param {string} [sources.disablePage] - disable-enterprise-features.adoc contents.
  * @param {string[]} [sources.allPropertyNames] - full property list for gating checks.
  * @returns {{findings: object[], features: object[], enumValues: string[]}}
@@ -223,7 +237,7 @@ function runChecks (sources) {
   }
   if (sources.infoCsv) {
     const plugins = parsers.parseConnectEnterprisePlugins(sources.infoCsv)
-    findings.push(...checkConnect(plugins, sources.antoraEnterpriseComponents))
+    findings.push(...checkConnect(plugins, features, sources.connectRef))
   } else {
     findings.push(finding('info', 'connect-list', 'Skipped: no connect info.csv provided.'))
   }

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()) {