@redpanda-data/docs-extensions-and-macros 4.12.5 → 4.13.0

package/bin/mcp-tools/telemetry.js

@@ -0,0 +1,211 @@
+/**
+ * Usage Telemetry and Statistics
+ *
+ * Tracks usage of prompts, resources, and tools to provide insights
+ * into adoption and identify unused features.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Usage statistics tracker
+ */
+class UsageStats {
+  constructor() {
+    this.prompts = new Map(); // name count
+    this.resources = new Map(); // uri count
+    this.tools = new Map(); // name count
+    this.startTime = new Date();
+    this.lastReportTime = new Date();
+  }
+
+  /**
+   * Record prompt usage
+   * @param {string} name - Prompt name
+   */
+  recordPrompt(name) {
+    const count = this.prompts.get(name) || 0;
+    this.prompts.set(name, count + 1);
+  }
+
+  /**
+   * Record resource usage
+   * @param {string} uri - Resource URI
+   */
+  recordResource(uri) {
+    const count = this.resources.get(uri) || 0;
+    this.resources.set(uri, count + 1);
+  }
+
+  /**
+   * Record tool usage
+   * @param {string} name - Tool name
+   */
+  recordTool(name) {
+    const count = this.tools.get(name) || 0;
+    this.tools.set(name, count + 1);
+  }
+
+  /**
+   * Get stats summary
+   * @returns {Object} Statistics summary
+   */
+  getSummary() {
+    const now = new Date();
+    const uptime = Math.floor((now - this.startTime) / 1000); // seconds
+    const timeSinceLastReport = Math.floor((now - this.lastReportTime) / 1000);
+
+    return {
+      uptime,
+      timeSinceLastReport,
+      promptCount: this.prompts.size,
+      resourceCount: this.resources.size,
+      toolCount: this.tools.size,
+      totalPromptCalls: Array.from(this.prompts.values()).reduce((a, b) => a + b, 0),
+      totalResourceCalls: Array.from(this.resources.values()).reduce((a, b) => a + b, 0),
+      totalToolCalls: Array.from(this.tools.values()).reduce((a, b) => a + b, 0),
+      prompts: Object.fromEntries(this.prompts),
+      resources: Object.fromEntries(this.resources),
+      tools: Object.fromEntries(this.tools)
+    };
+  }
+
+  /**
+   * Get top N most used items
+   * @param {Map} map - Map to get top from
+   * @param {number} n - Number of items
+   * @returns {Array} Top N items as [name, count] pairs
+   */
+  getTopN(map, n = 5) {
+    return Array.from(map.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, n);
+  }
+
+  /**
+   * Format stats for display
+   * @returns {string} Formatted stats
+   */
+  format() {
+    const summary = this.getSummary();
+    const lines = [];
+
+    lines.push('MCP Server Usage Statistics');
+    lines.push('='.repeat(60));
+    lines.push('');
+
+    // Uptime
+    const hours = Math.floor(summary.uptime / 3600);
+    const minutes = Math.floor((summary.uptime % 3600) / 60);
+    lines.push(`Uptime: ${hours}h ${minutes}m`);
+    lines.push('');
+
+    // Totals
+    lines.push(`Total calls:`);
+    lines.push(`  Prompts: ${summary.totalPromptCalls}`);
+    lines.push(`  Resources: ${summary.totalResourceCalls}`);
+    lines.push(`  Tools: ${summary.totalToolCalls}`);
+    lines.push('');
+
+    // Top prompts
+    if (this.prompts.size > 0) {
+      lines.push('Most used prompts:');
+      const topPrompts = this.getTopN(this.prompts, 5);
+      topPrompts.forEach(([name, count]) => {
+        lines.push(`  ${name}: ${count} calls`);
+      });
+      lines.push('');
+    }
+
+    // Top resources
+    if (this.resources.size > 0) {
+      lines.push('Most used resources:');
+      const topResources = this.getTopN(this.resources, 5);
+      topResources.forEach(([uri, count]) => {
+        lines.push(`  ${uri}: ${count} calls`);
+      });
+      lines.push('');
+    }
+
+    // Top tools
+    if (this.tools.size > 0) {
+      lines.push('Most used tools:');
+      const topTools = this.getTopN(this.tools, 5);
+      topTools.forEach(([name, count]) => {
+        lines.push(`  ${name}: ${count} calls`);
+      });
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Export stats to JSON file
+   * @param {string} filepath - Path to export to
+   */
+  exportToFile(filepath) {
+    const summary = this.getSummary();
+    summary.exportedAt = new Date().toISOString();
+
+    fs.writeFileSync(filepath, JSON.stringify(summary, null, 2), 'utf8');
+  }
+
+  /**
+   * Reset stats (for periodic reporting)
+   */
+  reset() {
+    this.lastReportTime = new Date();
+    // Don't reset the maps - keep cumulative stats
+  }
+}
+
+/**
+ * Create a periodic reporter
+ * @param {UsageStats} stats - Stats instance
+ * @param {number} intervalMs - Interval in milliseconds
+ * @returns {NodeJS.Timeout} Interval handle
+ */
+function createPeriodicReporter(stats, intervalMs = 3600000) {
+  return setInterval(() => {
+    const output = stats.format();
+    console.error('\n' + output);
+    stats.reset();
+  }, intervalMs);
+}
+
+/**
+ * Create a shutdown handler to export stats
+ * @param {UsageStats} stats - Stats instance
+ * @param {string} baseDir - Base directory for export
+ */
+function createShutdownHandler(stats, baseDir) {
+  const handler = () => {
+    const exportPath = path.join(baseDir, 'mcp-usage-stats.json');
+    try {
+      stats.exportToFile(exportPath);
+      console.error(`\nUsage stats exported to: ${exportPath}`);
+    } catch (err) {
+      console.error(`Failed to export usage stats: ${err.message}`);
+    }
+  };
+
+  process.on('SIGINT', () => {
+    handler();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    handler();
+    process.exit(0);
+  });
+
+  return handler;
+}
+
+module.exports = {
+  UsageStats,
+  createPeriodicReporter,
+  createShutdownHandler
+};

package/bin/mcp-tools/utils.js

@@ -0,0 +1,131 @@
+/**
+ * MCP Tools - Shared Utilities
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Constants
+const MAX_RECURSION_DEPTH = 3;
+const MAX_EXEC_BUFFER_SIZE = 50 * 1024 * 1024; // 50MB
+const DEFAULT_COMMAND_TIMEOUT = 10 * 60 * 1000; // 10 minutes
+const DEFAULT_SKIP_DIRS = ['node_modules', '.git', 'venv', '__pycache__', '.pytest_cache'];
+const PLAYBOOK_NAMES = [
+  'local-antora-playbook.yml',
+  'antora-playbook.yml',
+  'docs-playbook.yml'
+];
+
+/**
+ * Find the repository root from current working directory
+ * @param {string} [start=process.cwd()] - Starting directory for search
+ * @returns {{ root: string, detected: boolean, type: string|null }} Repository information
+ */
+function findRepoRoot(start = process.cwd()) {
+  let dir = start;
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      return { root: dir, detected: true, type: 'git' };
+    }
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return { root: dir, detected: true, type: 'npm' };
+    }
+    dir = path.dirname(dir);
+  }
+  return { root: start, detected: false, type: null };
+}
+
+/**
+ * Get the doc-tools command and arguments
+ * Handles both development mode (source repo) and installed mode (npm package)
+ * @param {Object} repoRoot - Repository root information from findRepoRoot()
+ * @returns {{ program: string, getArgs: function }} Command configuration
+ */
+function getDocToolsCommand(repoRoot) {
+  // Check if we're in the source repository (development mode)
+  const localDocTools = path.join(repoRoot.root, 'bin', 'doc-tools.js');
+  if (fs.existsSync(localDocTools)) {
+    return {
+      program: 'node',
+      getArgs: (cmdArgs) => [localDocTools, ...cmdArgs]
+    };
+  }
+
+  // Otherwise use npx, which will find the installed package in node_modules
+  return {
+    program: 'npx',
+    getArgs: (cmdArgs) => ['doc-tools', ...cmdArgs]
+  };
+}
+
+/**
+ * Execute a command safely using spawnSync (no shell)
+ * @param {string} program - Program to execute (for example, 'npx')
+ * @param {string[]} args - Array of arguments (for example, ['doc-tools', 'generate', 'property-docs'])
+ * @param {Object} options - Execution options
+ * @returns {string} Command output (stdout)
+ * @throws {Error} Error with stdout, stderr, and status properties on failure
+ */
+function executeCommand(program, args, options = {}) {
+  const defaultOptions = {
+    encoding: 'utf8',
+    maxBuffer: MAX_EXEC_BUFFER_SIZE,
+    timeout: DEFAULT_COMMAND_TIMEOUT,
+    stdio: 'pipe'
+  };
+
+  const result = spawnSync(program, args, { ...defaultOptions, ...options });
+
+  // Check for spawn errors
+  if (result.error) {
+    const err = new Error(`Failed to execute command: ${result.error.message}`);
+    err.stdout = result.stdout || '';
+    err.stderr = result.stderr || '';
+    err.status = result.status;
+    throw err;
+  }
+
+  // Check for non-zero exit codes
+  if (result.status !== 0) {
+    const errorMsg = result.stderr || `Command failed with exit code ${result.status}`;
+    const err = new Error(errorMsg);
+    err.stdout = result.stdout || '';
+    err.stderr = result.stderr || '';
+    err.status = result.status;
+    throw err;
+  }
+
+  return result.stdout;
+}
+
+/**
+ * Normalize version string (remove 'v' prefix if present)
+ * @param {string} version - Version string
+ * @returns {string} Normalized version
+ */
+function normalizeVersion(version) {
+  return version.startsWith('v') ? version.substring(1) : version;
+}
+
+/**
+ * Format date as YYYY-MM-DD
+ * @param {Date} date - Date to format
+ * @returns {string} Formatted date string
+ */
+function formatDate(date = new Date()) {
+  return date.toISOString().split('T')[0];
+}
+
+module.exports = {
+  MAX_RECURSION_DEPTH,
+  MAX_EXEC_BUFFER_SIZE,
+  DEFAULT_COMMAND_TIMEOUT,
+  DEFAULT_SKIP_DIRS,
+  PLAYBOOK_NAMES,
+  findRepoRoot,
+  getDocToolsCommand,
+  executeCommand,
+  normalizeVersion,
+  formatDate
+};

package/bin/mcp-tools/versions.js

@@ -0,0 +1,168 @@
+/**
+ * MCP Tools - Version Information
+ *
+ * OPTIMIZATION: This tool calls CLI and caches results.
+ * - Caches version info for 5 minutes (rarely changes)
+ * - No model recommendation (CLI tool)
+ * - Recommended model: haiku (if LLM processing needed)
+ */
+
+const { spawnSync } = require('child_process');
+const { findRepoRoot, getDocToolsCommand } = require('./utils');
+const cache = require('./cache');
+
+/**
+ * Get the latest Redpanda version information
+ * @param {Object} args - Arguments
+ * @param {boolean} [args.beta] - Whether to get beta/RC version
+ * @returns {Object} Version information
+ */
+function getRedpandaVersion(args = {}) {
+  // Check cache first (5 minute TTL)
+  const cacheKey = `redpanda-version:${args.beta ? 'beta' : 'stable'}`;
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    return { ...cached, _cached: true };
+  }
+
+  try {
+    // Get doc-tools command (handles both local and installed)
+    const repoRoot = findRepoRoot();
+    const docTools = getDocToolsCommand(repoRoot);
+
+    // Build command arguments array
+    const baseArgs = ['get-redpanda-version'];
+    if (args.beta) {
+      baseArgs.push('--beta');
+    }
+
+    const cmdResult = spawnSync(docTools.program, docTools.getArgs(baseArgs), {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 30000
+    });
+
+    // Check for errors
+    if (cmdResult.error) {
+      throw new Error(`Failed to execute command: ${cmdResult.error.message}`);
+    }
+
+    if (cmdResult.status !== 0) {
+      const errorMsg = cmdResult.stderr || `Command failed with exit code ${cmdResult.status}`;
+      throw new Error(errorMsg);
+    }
+
+    const output = cmdResult.stdout;
+
+    // Parse the output (format: REDPANDA_VERSION=vX.Y.Z\nREDPANDA_DOCKER_REPO=redpanda)
+    const lines = output.trim().split('\n');
+    const versionLine = lines.find(l => l.startsWith('REDPANDA_VERSION='));
+    const dockerLine = lines.find(l => l.startsWith('REDPANDA_DOCKER_REPO='));
+
+    if (!versionLine) {
+      return {
+        success: false,
+        error: 'Failed to parse version from output'
+      };
+    }
+
+    const version = versionLine.split('=')[1];
+    const dockerRepo = dockerLine ? dockerLine.split('=')[1] : 'redpanda';
+
+    const result = {
+      success: true,
+      version,
+      docker_tag: `docker.redpanda.com/redpandadata/${dockerRepo}:${version}`,
+      is_beta: args.beta || false,
+      notes_url: `https://github.com/redpanda-data/redpanda/releases/tag/${version}`,
+      _modelRecommendation: 'haiku'
+    };
+
+    // Cache for 5 minutes
+    cache.set(cacheKey, result, 5 * 60 * 1000);
+
+    return result;
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      suggestion: 'Make sure you have network access to fetch version information from GitHub'
+    };
+  }
+}
+
+/**
+ * Get the latest Redpanda Console version information
+ * @returns {Object} Version information
+ */
+function getConsoleVersion() {
+  // Check cache first (5 minute TTL)
+  const cacheKey = 'console-version';
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    return { ...cached, _cached: true };
+  }
+
+  try {
+    // Get doc-tools command (handles both local and installed)
+    const repoRoot = findRepoRoot();
+    const docTools = getDocToolsCommand(repoRoot);
+
+    const cmdResult = spawnSync(docTools.program, docTools.getArgs(['get-console-version']), {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      timeout: 30000
+    });
+
+    // Check for errors
+    if (cmdResult.error) {
+      throw new Error(`Failed to execute command: ${cmdResult.error.message}`);
+    }
+
+    if (cmdResult.status !== 0) {
+      const errorMsg = cmdResult.stderr || `Command failed with exit code ${cmdResult.status}`;
+      throw new Error(errorMsg);
+    }
+
+    const output = cmdResult.stdout;
+
+    // Parse the output (format: CONSOLE_VERSION=vX.Y.Z\nCONSOLE_DOCKER_REPO=console)
+    const lines = output.trim().split('\n');
+    const versionLine = lines.find(l => l.startsWith('CONSOLE_VERSION='));
+    const dockerLine = lines.find(l => l.startsWith('CONSOLE_DOCKER_REPO='));
+
+    if (!versionLine) {
+      return {
+        success: false,
+        error: 'Failed to parse version from output'
+      };
+    }
+
+    const version = versionLine.split('=')[1];
+    const dockerRepo = dockerLine ? dockerLine.split('=')[1] : 'console';
+
+    const result = {
+      success: true,
+      version,
+      docker_tag: `docker.redpanda.com/redpandadata/${dockerRepo}:${version}`,
+      notes_url: `https://github.com/redpanda-data/console/releases/tag/${version}`,
+      _modelRecommendation: 'haiku'
+    };
+
+    // Cache for 5 minutes
+    cache.set(cacheKey, result, 5 * 60 * 1000);
+
+    return result;
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      suggestion: 'Make sure you have network access to fetch version information from GitHub'
+    };
+  }
+}
+
+module.exports = {
+  getRedpandaVersion,
+  getConsoleVersion
+};

package/cli-utils/convert-doc-links.js

@@ -3,7 +3,7 @@ const { URL } = require('url');
 /**
  * Converts a docs.redpanda.com URL, optionally suffixed with a label in brackets, into an Antora xref resource ID string.
  *
- * If the input includes a label in square brackets (e.g., `[Label]`), the label is preserved and appended to the resulting xref.
+ * If the input includes a label in square brackets (for example, `[Label]`), the label is preserved and appended to the resulting xref.
  *
  * @param {string} input - A docs.redpanda.com URL, optionally followed by a label in square brackets.
  * @returns {string} The corresponding Antora xref resource ID, with the label preserved if present.

package/cli-utils/github-token.js

@@ -0,0 +1,58 @@
+/**
+ * GitHub Token Utility
+ *
+ * Provides a consistent way to retrieve GitHub tokens from environment variables.
+ * Supports multiple common token variable names with priority order.
+ */
+
+/**
+ * Get GitHub token from environment variables
+ * Checks multiple common variable names in priority order:
+ * 1. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
+ * 2. GITHUB_TOKEN - GitHub Actions default
+ * 3. GH_TOKEN - GitHub CLI default
+ *
+ * @returns {string|null} GitHub token or null if not found
+ */
+function getGitHubToken() {
+  return process.env.REDPANDA_GITHUB_TOKEN ||
+         process.env.GITHUB_TOKEN ||
+         process.env.GH_TOKEN ||
+         null;
+}
+
+/**
+ * Get an authenticated GitHub URL by injecting the token
+ * @param {string} url - The GitHub HTTPS URL (for example, https://github.com/owner/repo.git)
+ * @returns {string} Authenticated URL with token, or original URL if no token available
+ */
+function getAuthenticatedGitHubUrl(url) {
+  const token = getGitHubToken();
+
+  if (!token || !url.includes('github.com')) {
+    return url;
+  }
+
+  try {
+    const urlObj = new URL(url);
+    urlObj.username = token;
+    return urlObj.toString();
+  } catch (err) {
+    // If URL parsing fails, return original
+    return url;
+  }
+}
+
+/**
+ * Check if a GitHub token is available
+ * @returns {boolean} True if a token is available
+ */
+function hasGitHubToken() {
+  return getGitHubToken() !== null;
+}
+
+module.exports = {
+  getGitHubToken,
+  getAuthenticatedGitHubUrl,
+  hasGitHubToken
+};

package/cli-utils/self-managed-docs-branch.js

@@ -5,7 +5,7 @@ const { spawnSync } = require('child_process');
 /**
  * Retrieves the current Self-Managed documentation version from the remote antora.yml file.
  *
- * @returns {Promise<string>} Resolves with the version string (e.g., "25.1").
+ * @returns {Promise<string>} Resolves with the version string (for example, "25.1").
  *
  * @throws {Error} If the antora.yml file cannot be fetched, parsed, or if the version field is missing.
  */
@@ -39,7 +39,7 @@ function fetchRemoteAntoraVersion() {
  *
  * Normalizes the input tag, extracts the major.minor version, and applies version-specific logic to select the correct branch. Verifies that the chosen branch exists in the remote repository.
  *
- * @param {string} operatorTag - The operator tag to evaluate (e.g., "operator/v25.1.2" or "v25.1.2").
+ * @param {string} operatorTag - The operator tag to evaluate (for example, "operator/v25.1.2" or "v25.1.2").
  * @returns {Promise<string>} The name of the documentation branch to use.
  *
  * @throws {Error} If the tag cannot be parsed or if the determined branch does not exist in the remote repository.