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

package/bin/mcp-tools/helm-docs.js

@@ -0,0 +1,152 @@
+/**
+ * MCP Tools - Helm Chart Documentation Generation
+ *
+ * OPTIMIZATION: This tool calls CLI, doesn't use LLM directly.
+ * - No model recommendation (CLI tool)
+ * - Cost comes from doc-tools CLI execution
+ */
+
+const { spawnSync } = require('child_process');
+const { findRepoRoot, getDocToolsCommand, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+const { getAntoraStructure } = require('./antora');
+
+/**
+ * Generate Helm chart documentation
+ *
+ * Use tags for released content (GA or beta), branches for in-progress content.
+ * When using GitHub URLs, requires either --tag or --branch to be specified.
+ * Auto-prepends "operator/" for tags when using redpanda-operator repository.
+ *
+ * @param {Object} args - Arguments
+ * @param {string} [args.chart_dir] - Chart directory, root, or GitHub URL
+ * @param {string} [args.tag] - Git tag for released content when using GitHub URL (auto-prepends "operator/" for redpanda-operator repository)
+ * @param {string} [args.branch] - Branch name for in-progress content when using GitHub URL
+ * @param {string} [args.readme] - Relative README.md path inside each chart dir
+ * @param {string} [args.output_dir] - Where to write generated AsciiDoc files
+ * @param {string} [args.output_suffix] - Suffix to append to each chart name
+ * @returns {Object} Generation results
+ */
+function generateHelmDocs(args = {}) {
+  const repoRoot = findRepoRoot();
+  const structure = getAntoraStructure(repoRoot);
+
+  if (!structure.hasDocTools) {
+    return {
+      success: false,
+      error: 'doc-tools not found in this repository',
+      suggestion: 'Navigate to the docs-extensions-and-macros repository'
+    };
+  }
+
+  // Validate that tag and branch are mutually exclusive
+  if (args.tag && args.branch) {
+    return {
+      success: false,
+      error: 'Cannot specify both tag and branch',
+      suggestion: 'Use either --tag or --branch, not both'
+    };
+  }
+
+  try {
+    // Normalize tag: add 'v' prefix if not present
+    let normalizedTag = null;
+    if (args.tag) {
+      normalizedTag = args.tag;
+      if (!normalizedTag.startsWith('v')) {
+        normalizedTag = `v${normalizedTag}`;
+      }
+    }
+
+    // Get doc-tools command (handles both local and installed)
+    const docTools = getDocToolsCommand(repoRoot);
+
+    // Build command arguments array
+    const baseArgs = ['generate', 'helm-spec'];
+
+    if (args.chart_dir) {
+      baseArgs.push('--chart-dir');
+      baseArgs.push(args.chart_dir);
+    }
+
+    if (normalizedTag) {
+      baseArgs.push('--tag');
+      baseArgs.push(normalizedTag);
+    } else if (args.branch) {
+      baseArgs.push('--branch');
+      baseArgs.push(args.branch);
+    }
+
+    if (args.readme) {
+      baseArgs.push('--readme');
+      baseArgs.push(args.readme);
+    }
+
+    if (args.output_dir) {
+      baseArgs.push('--output-dir');
+      baseArgs.push(args.output_dir);
+    }
+
+    if (args.output_suffix) {
+      baseArgs.push('--output-suffix');
+      baseArgs.push(args.output_suffix);
+    }
+
+    const result = spawnSync(docTools.program, docTools.getArgs(baseArgs), {
+      cwd: repoRoot.root,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: MAX_EXEC_BUFFER_SIZE,
+      timeout: DEFAULT_COMMAND_TIMEOUT
+    });
+
+    // 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;
+    }
+
+    const output = result.stdout;
+
+    // Parse output to extract information
+    const chartCountMatch = output.match(/(\d+) charts?/i);
+
+    const refType = normalizedTag ? 'tag' : args.branch ? 'branch' : null;
+    const gitRef = normalizedTag || args.branch;
+
+    return {
+      success: true,
+      ...(refType && { [refType]: gitRef }),
+      chart_dir: args.chart_dir || 'default',
+      charts_documented: chartCountMatch ? parseInt(chartCountMatch[1]) : null,
+      files_generated: [args.output_dir || 'modules/reference/pages'],
+      output: output.trim(),
+      summary: `Generated Helm chart documentation${gitRef ? ` for ${refType} ${gitRef}` : ''}`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status,
+      suggestion: 'Check that the chart directory or GitHub URL is valid and accessible'
+    };
+  }
+}
+
+module.exports = {
+  generateHelmDocs
+};

package/bin/mcp-tools/index.js

@@ -0,0 +1,245 @@
+/**
+ * MCP Tools - Main Exports
+ *
+ * This module exports all MCP tools in a modular structure.
+ */
+
+// Utilities
+const { findRepoRoot, executeCommand, normalizeVersion, formatDate } = require('./utils');
+
+// Antora
+const { getAntoraStructure } = require('./antora');
+
+// Versions
+const { getRedpandaVersion, getConsoleVersion } = require('./versions');
+
+// Documentation generation tools
+const { generatePropertyDocs } = require('./property-docs');
+const { generateMetricsDocs } = require('./metrics-docs');
+const { generateRpkDocs } = require('./rpk-docs');
+const { generateRpConnectDocs } = require('./rpcn-docs');
+const { generateHelmDocs } = require('./helm-docs');
+const { generateCloudRegions } = require('./cloud-regions');
+const { generateCrdDocs } = require('./crd-docs');
+const { generateBundleOpenApi } = require('./openapi');
+
+// Review tools
+const { reviewGeneratedDocs, generateReviewReport } = require('./generated-docs-review');
+const { reviewContent } = require('./content-review');
+
+// Job queue
+const { initializeJobQueue, createJob, getJob, listJobs, cleanupOldJobs } = require('./job-queue');
+
+/**
+ * Execute a tool and return results
+ * @param {string} toolName - Name of the tool to execute
+ * @param {Object} args - Arguments for the tool
+ * @returns {Object} Tool execution results
+ */
+function executeTool(toolName, args = {}) {
+  const repoRoot = findRepoRoot();
+
+  try {
+    switch (toolName) {
+      case 'get_antora_structure':
+        return getAntoraStructure(repoRoot);
+
+      case 'get_redpanda_version':
+        return getRedpandaVersion(args);
+
+      case 'get_console_version':
+        return getConsoleVersion();
+
+      case 'generate_property_docs':
+        return generatePropertyDocs(args);
+
+      case 'generate_metrics_docs':
+        return generateMetricsDocs(args);
+
+      case 'generate_rpk_docs':
+        return generateRpkDocs(args);
+
+      case 'generate_rpcn_connector_docs':
+        return generateRpConnectDocs(args);
+
+      case 'generate_helm_docs':
+        return generateHelmDocs(args);
+
+      case 'generate_cloud_regions':
+        return generateCloudRegions(args);
+
+      case 'generate_crd_docs':
+        return generateCrdDocs(args);
+
+      case 'generate_bundle_openapi':
+        return generateBundleOpenApi(args);
+
+      case 'review_generated_docs':
+        return reviewGeneratedDocs(args);
+
+      case 'review_content':
+        return reviewContent(args, repoRoot.root);
+
+      case 'run_doc_tools_command': {
+        // Validate and execute raw doc-tools command
+        if (!args || typeof args !== 'object') {
+          return {
+            success: false,
+            error: 'Invalid arguments: expected an object'
+          };
+        }
+
+        const validation = validateDocToolsCommand(args.command);
+        if (!validation.valid) {
+          return {
+            success: false,
+            error: validation.error
+          };
+        }
+
+        try {
+          // Get doc-tools command (handles both local and installed)
+          const { getDocToolsCommand } = require('./utils');
+          const docTools = getDocToolsCommand(repoRoot);
+
+          // Parse command into argument array (no shell interpolation)
+          // Since validation already rejects shell metacharacters, we can safely split by spaces
+          // Handle quoted strings for paths with spaces
+          const cmdArgs = parseCommandArgs(args.command);
+
+          // Build full args using the appropriate command
+          const fullArgs = docTools.getArgs(cmdArgs);
+
+          const output = executeCommand(docTools.program, fullArgs, {
+            cwd: repoRoot.root
+          });
+
+          return {
+            success: true,
+            output: output.trim(),
+            command: `${docTools.program} ${fullArgs.join(' ')}`
+          };
+        } catch (err) {
+          return {
+            success: false,
+            error: err.message,
+            stdout: err.stdout || '',
+            stderr: err.stderr || ''
+          };
+        }
+      }
+
+      default:
+        return {
+          success: false,
+          error: `Unknown tool: ${toolName}`,
+          suggestion: 'Check the tool name and try again'
+        };
+    }
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      suggestion: 'An unexpected error occurred while executing the tool'
+    };
+  }
+}
+
+/**
+ * Parse command string into array of arguments
+ * Handles quoted strings for paths with spaces
+ * @param {string} command - The command string to parse
+ * @returns {string[]} Array of arguments
+ */
+function parseCommandArgs(command) {
+  const args = [];
+  let current = '';
+  let inQuotes = false;
+  let quoteChar = '';
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i];
+
+    if ((char === '"' || char === "'") && !inQuotes) {
+      // Start of quoted string
+      inQuotes = true;
+      quoteChar = char;
+    } else if (char === quoteChar && inQuotes) {
+      // End of quoted string
+      inQuotes = false;
+      quoteChar = '';
+    } else if (char === ' ' && !inQuotes) {
+      // Space outside quotes - end of argument
+      if (current) {
+        args.push(current);
+        current = '';
+      }
+    } else {
+      // Regular character
+      current += char;
+    }
+  }
+
+  // Add final argument if present
+  if (current) {
+    args.push(current);
+  }
+
+  return args;
+}
+
+/**
+ * Validate doc-tools command to prevent command injection
+ * @param {string} command - The command string to validate
+ * @returns {{ valid: boolean, error?: string }} Validation result
+ */
+function validateDocToolsCommand(command) {
+  if (!command || typeof command !== 'string') {
+    return { valid: false, error: 'Command must be a non-empty string' };
+  }
+
+  const dangerousChars = /[;|&$`<>(){}[\]!*?~]/;
+  if (dangerousChars.test(command)) {
+    return {
+      valid: false,
+      error: 'Invalid command: shell metacharacters not allowed. Use simple doc-tools commands only.'
+    };
+  }
+
+  if (command.includes('..') || command.includes('~')) {
+    return {
+      valid: false,
+      error: 'Invalid command: path traversal sequences not allowed'
+    };
+  }
+
+  return { valid: true };
+}
+
+module.exports = {
+  // Core functions
+  findRepoRoot,
+  executeTool,
+
+  // Individual tool exports (for testing or direct use)
+  getAntoraStructure,
+  getRedpandaVersion,
+  getConsoleVersion,
+  generatePropertyDocs,
+  generateMetricsDocs,
+  generateRpkDocs,
+  generateRpConnectDocs,
+  generateHelmDocs,
+  generateCloudRegions,
+  generateCrdDocs,
+  generateBundleOpenApi,
+  reviewGeneratedDocs,
+  generateReviewReport,
+
+  // Job queue
+  initializeJobQueue,
+  createJob,
+  getJob,
+  listJobs,
+  cleanupOldJobs
+};