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

package/bin/mcp-tools/antora.js

@@ -0,0 +1,153 @@
+/**
+ * MCP Tools - Antora Structure
+ *
+ * OPTIMIZATION: This tool uses caching and should use Haiku model.
+ * - Caches structure for 1 hour (rarely changes)
+ * - No complex reasoning required (just directory scanning)
+ * - Recommended model: haiku
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { MAX_RECURSION_DEPTH, DEFAULT_SKIP_DIRS, PLAYBOOK_NAMES } = require('./utils');
+const cache = require('./cache');
+
+/**
+ * Get Antora structure information for the current repository
+ * @param {string|{root: string, detected: boolean, type: string|null}} repoRoot - Repository root path or info object
+ * @param {string[]} [skipDirs=DEFAULT_SKIP_DIRS] - Directories to skip during search
+ * @param {Object} [options] - Additional options
+ * @param {boolean} [options.skipCache] - Skip cache and force fresh scan
+ * @returns {Object} Antora structure information
+ */
+function getAntoraStructure(repoRoot, skipDirs = DEFAULT_SKIP_DIRS, options = {}) {
+  const rootPath = typeof repoRoot === 'string' ? repoRoot : repoRoot.root;
+  const repoInfo = typeof repoRoot === 'object' ? repoRoot : { root: repoRoot, detected: true, type: null };
+
+  // Check cache first (1 hour TTL)
+  const cacheKey = `antora-structure:${rootPath}`;
+  if (!options.skipCache) {
+    const cached = cache.get(cacheKey);
+    if (cached) {
+      return {
+        ...cached,
+        _cached: true,
+        _cacheHit: true
+      };
+    }
+  }
+
+  const playbookPath = PLAYBOOK_NAMES
+    .map(name => path.join(rootPath, name))
+    .find(p => fs.existsSync(p));
+
+  let playbookContent = null;
+  if (playbookPath) {
+    try {
+      playbookContent = yaml.load(fs.readFileSync(playbookPath, 'utf8'));
+    } catch (err) {
+      console.error(`Warning: Failed to parse playbook at ${playbookPath}: ${err.message}`);
+    }
+  }
+
+  const antoraYmls = [];
+  const findAntoraYmls = (dir, depth = 0, visited = new Set()) => {
+    if (depth > MAX_RECURSION_DEPTH || !fs.existsSync(dir)) return;
+
+    try {
+      const realPath = fs.realpathSync(dir);
+      if (visited.has(realPath)) return;
+      visited.add(realPath);
+
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (skipDirs.includes(entry.name)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          findAntoraYmls(fullPath, depth + 1, visited);
+        } else if (entry.name === 'antora.yml') {
+          antoraYmls.push(fullPath);
+        }
+      }
+    } catch (err) {
+      console.error(`Warning: Failed to read directory ${dir}: ${err.message}`);
+    }
+  };
+  findAntoraYmls(rootPath);
+
+  const components = antoraYmls.map(ymlPath => {
+    try {
+      const content = yaml.load(fs.readFileSync(ymlPath, 'utf8'));
+      const componentDir = path.dirname(ymlPath);
+      const modulesDir = path.join(componentDir, 'modules');
+      const modules = fs.existsSync(modulesDir)
+        ? fs.readdirSync(modulesDir).filter(m => {
+            const stat = fs.statSync(path.join(modulesDir, m));
+            return stat.isDirectory();
+          })
+        : [];
+
+      return {
+        name: content.name,
+        version: content.version,
+        title: content.title,
+        path: componentDir,
+        modules: modules.map(moduleName => {
+          const modulePath = path.join(modulesDir, moduleName);
+          return {
+            name: moduleName,
+            path: modulePath,
+            pages: fs.existsSync(path.join(modulePath, 'pages')),
+            partials: fs.existsSync(path.join(modulePath, 'partials')),
+            examples: fs.existsSync(path.join(modulePath, 'examples')),
+            attachments: fs.existsSync(path.join(modulePath, 'attachments')),
+            images: fs.existsSync(path.join(modulePath, 'images')),
+          };
+        }),
+      };
+    } catch (err) {
+      return { error: `Failed to parse ${ymlPath}: ${err.message}` };
+    }
+  });
+
+  const result = {
+    repoRoot: rootPath,
+    repoInfo,
+    playbook: playbookContent,
+    playbookPath,
+    components,
+    hasDocTools: (() => {
+      // Check if we're in the source repo (docs-extensions-and-macros)
+      if (fs.existsSync(path.join(rootPath, 'bin', 'doc-tools.js'))) {
+        return true;
+      }
+
+      // Check if doc-tools is available via npx or as installed dependency
+      try {
+        const { execSync } = require('child_process');
+        execSync('npx doc-tools --version', {
+          stdio: 'ignore',
+          timeout: 5000,
+          cwd: rootPath
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    })(),
+    // Metadata for cost optimization
+    _modelRecommendation: 'haiku',
+    _reasoning: 'Simple directory scanning, no complex reasoning required'
+  };
+
+  // Cache for 1 hour
+  cache.set(cacheKey, result, 60 * 60 * 1000);
+
+  return result;
+}
+
+module.exports = {
+  getAntoraStructure
+};

package/bin/mcp-tools/cache.js

@@ -0,0 +1,89 @@
+/**
+ * Simple in-memory cache for MCP tools
+ *
+ * Reduces costs by caching expensive operations like:
+ * - Style guide loading
+ * - Antora structure scanning
+ * - Static content that rarely changes
+ */
+
+const cache = new Map();
+
+/**
+ * Get a cached value
+ * @param {string} key - Cache key
+ * @returns {any|null} Cached value or null if not found/expired
+ */
+function get(key) {
+  const entry = cache.get(key);
+  if (!entry) return null;
+
+  // Check if expired
+  if (entry.expiresAt && Date.now() > entry.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+
+  return entry.value;
+}
+
+/**
+ * Set a cached value
+ * @param {string} key - Cache key
+ * @param {any} value - Value to cache
+ * @param {number} ttl - Time to live in milliseconds (default: 1 hour)
+ */
+function set(key, value, ttl = 60 * 60 * 1000) {
+  cache.set(key, {
+    value,
+    expiresAt: ttl ? Date.now() + ttl : null
+  });
+}
+
+/**
+ * Clear all cached values
+ */
+function clear() {
+  cache.clear();
+}
+
+/**
+ * Clear expired entries
+ */
+function prune() {
+  const now = Date.now();
+  for (const [key, entry] of cache.entries()) {
+    if (entry.expiresAt && now > entry.expiresAt) {
+      cache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get or compute a value (cache aside pattern)
+ * @param {string} key - Cache key
+ * @param {Function} compute - Function to compute value if not cached
+ * @param {number} ttl - Time to live in milliseconds
+ * @returns {Promise<any>} Cached or computed value
+ */
+async function getOrCompute(key, compute, ttl = 60 * 60 * 1000) {
+  const cached = get(key);
+  if (cached !== null) {
+    return cached;
+  }
+
+  const value = await compute();
+  set(key, value, ttl);
+  return value;
+}
+
+// Prune expired entries every 5 minutes
+setInterval(prune, 5 * 60 * 1000);
+
+module.exports = {
+  get,
+  set,
+  clear,
+  prune,
+  getOrCompute
+};

package/bin/mcp-tools/cloud-regions.js

@@ -0,0 +1,127 @@
+/**
+ * MCP Tools - Cloud Regions Table Generation
+ */
+
+const { spawnSync } = require('child_process');
+const { findRepoRoot, getDocToolsCommand, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+const { getAntoraStructure } = require('./antora');
+
+/**
+ * Generate cloud regions table documentation
+ * @param {Object} args - Arguments
+ * @param {string} [args.output] - Output file path (relative to repo root)
+ * @param {string} [args.format] - Output format: 'md' or 'adoc'
+ * @param {string} [args.owner] - GitHub repository owner
+ * @param {string} [args.repo] - GitHub repository name
+ * @param {string} [args.path] - Path to YAML file in repository
+ * @param {string} [args.ref] - Git reference (branch, tag, or commit SHA)
+ * @param {string} [args.template] - Path to custom Handlebars template
+ * @param {boolean} [args.dry_run] - Print output to stdout instead of writing file
+ * @returns {Object} Generation results
+ */
+function generateCloudRegions(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'
+    };
+  }
+
+  try {
+    // Get doc-tools command (handles both local and installed)
+    const docTools = getDocToolsCommand(repoRoot);
+
+    // Build command arguments array
+    const baseArgs = ['generate', 'cloud-regions'];
+
+    if (args.output) {
+      baseArgs.push('--output');
+      baseArgs.push(args.output);
+    }
+
+    if (args.format) {
+      baseArgs.push('--format');
+      baseArgs.push(args.format);
+    }
+
+    if (args.owner) {
+      baseArgs.push('--owner');
+      baseArgs.push(args.owner);
+    }
+
+    if (args.repo) {
+      baseArgs.push('--repo');
+      baseArgs.push(args.repo);
+    }
+
+    if (args.path) {
+      baseArgs.push('--path');
+      baseArgs.push(args.path);
+    }
+
+    if (args.ref) {
+      baseArgs.push('--ref');
+      baseArgs.push(args.ref);
+    }
+
+    if (args.template) {
+      baseArgs.push('--template');
+      baseArgs.push(args.template);
+    }
+
+    if (args.dry_run) {
+      baseArgs.push('--dry-run');
+    }
+
+    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) {
+      throw new Error(`Failed to execute command: ${result.error.message}`);
+    }
+
+    // Check for non-zero exit codes
+    if (result.status !== 0) {
+      const errorMsg = result.stderr || `Command failed with exit code ${result.status}`;
+      throw new Error(errorMsg);
+    }
+
+    const output = result.stdout;
+
+    // Parse output to extract information
+    const regionCountMatch = output.match(/(\d+) regions?/i);
+
+    return {
+      success: true,
+      format: args.format || 'md',
+      ref: args.ref || 'integration',
+      regions_documented: regionCountMatch ? parseInt(regionCountMatch[1]) : null,
+      files_generated: args.dry_run ? [] : [args.output || 'cloud-controlplane/x-topics/cloud-regions.md'],
+      output: output.trim(),
+      summary: `Generated cloud regions table from GitHub YAML`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status,
+      suggestion: 'Check that you have access to the GitHub repository and the YAML file exists'
+    };
+  }
+}
+
+module.exports = {
+  generateCloudRegions
+};

package/bin/mcp-tools/content-review.js

@@ -0,0 +1,196 @@
+/**
+ * Content Review Tool
+ *
+ * Provides comprehensive content review with automatic style guide context.
+ * This tool automatically fetches the style guide and provides review instructions,
+ * so the LLM has everything needed in a single call.
+ *
+ * OPTIMIZATION: Caches style guide and review instructions.
+ * - Style guide cached for 1 hour (rarely changes)
+ * - Review instructions cached permanently (static)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const cache = require('./cache');
+
+/**
+ * Review content with automatic style guide context
+ * @param {Object} args - Tool arguments
+ * @param {string} args.content - Content to review
+ * @param {string} [args.focus] - What to focus on (comprehensive, style, terminology, clarity)
+ * @param {string} [baseDir] - Base directory for finding resources
+ * @returns {Object} Review context including style guide
+ */
+function reviewContent(args, baseDir) {
+  if (!args || !args.content) {
+    return {
+      success: false,
+      error: 'Missing required parameter: content'
+    };
+  }
+
+  const focus = args.focus || 'comprehensive';
+
+  // Validate focus parameter
+  const validFocus = ['comprehensive', 'style', 'terminology', 'clarity'];
+  if (!validFocus.includes(focus)) {
+    return {
+      success: false,
+      error: `Invalid focus parameter. Must be one of: ${validFocus.join(', ')}`
+    };
+  }
+
+  // Find base directory (either provided or from repo root)
+  const actualBaseDir = baseDir || path.join(__dirname, '../..');
+
+  // Load style guide resource (with caching)
+  const styleGuidePath = path.join(actualBaseDir, 'mcp', 'team-standards', 'style-guide.md');
+  const cacheKey = 'style-guide-content';
+
+  let styleGuide = cache.get(cacheKey);
+
+  if (!styleGuide) {
+    if (!fs.existsSync(styleGuidePath)) {
+      return {
+        success: false,
+        error: `Style guide not found at: ${styleGuidePath}`,
+        suggestion: 'Ensure the MCP server is running from the correct directory'
+      };
+    }
+
+    try {
+      styleGuide = fs.readFileSync(styleGuidePath, 'utf8');
+      cache.set(cacheKey, styleGuide, 60 * 60 * 1000); // Cache for 1 hour
+    } catch (err) {
+      return {
+        success: false,
+        error: `Failed to read style guide: ${err.message}`
+      };
+    }
+  }
+
+  // Build review instructions based on focus (cached permanently as they're static)
+  const instructionsCacheKey = `review-instructions:${focus}`;
+  let instructions = cache.get(instructionsCacheKey);
+
+  if (!instructions) {
+    instructions = buildReviewInstructions(focus);
+    cache.set(instructionsCacheKey, instructions, 24 * 60 * 60 * 1000); // Cache for 24 hours
+  }
+
+  // Return the bundled context
+  return {
+    success: true,
+    message: 'Style guide loaded. Please review the content according to the instructions below.',
+    styleGuide,
+    instructions,
+    content: args.content,
+    focus,
+    // Provide formatted output that LLM can easily parse
+    reviewContext: formatReviewContext(styleGuide, instructions, args.content, focus)
+  };
+}
+
+/**
+ * Build review instructions based on focus area
+ * @param {string} focus - What to focus on
+ * @returns {string} Review instructions
+ */
+function buildReviewInstructions(focus) {
+  const baseInstructions = `
+# Content Review Instructions
+
+You are reviewing documentation for the Redpanda documentation team.
+
+The style guide has been automatically loaded for your reference.
+
+## Your task
+
+Review the provided content and provide detailed, actionable feedback.
+`;
+
+  const focusInstructions = {
+    comprehensive: `
+Review all aspects of the content:
+
+1. **Style violations** - Check against the style guide (capitalization, formatting, structure)
+2. **Terminology issues** - Verify correct usage of approved terms
+3. **Voice and tone** - Ensure consistent, appropriate tone
+4. **Clarity and readability** - Identify confusing or unclear sections
+5. **Technical accuracy** - Flag any technical issues (if detectable)
+6. **Formatting** - Check AsciiDoc formatting, code blocks, lists
+7. **Accessibility** - Verify heading hierarchy, alt text, link text
+
+Provide specific line numbers or sections for each issue found.
+`,
+    style: `
+Focus on style guide compliance:
+
+1. **Formatting violations** - Capitalization, punctuation, spacing
+2. **Structural issues** - Heading hierarchy, section organization
+3. **Voice and tone** - Too formal, too casual, or inconsistent
+4. **Style guide rules** - Any violations of documented standards
+
+Reference specific style guide sections when identifying issues.
+`,
+    terminology: `
+Focus on terminology:
+
+1. **Incorrect terms** - Wrong capitalization, spelling, or usage
+2. **Deprecated terms** - Outdated terms that should be replaced
+3. **Inconsistent usage** - Same concept referred to differently
+4. **Missing approved terms** - Concepts that should use glossary terms
+
+Check against the terminology section of the style guide.
+`,
+    clarity: `
+Focus on clarity and readability:
+
+1. **Complex sentences** - Sentences that are too long or convoluted
+2. **Unclear explanations** - Technical concepts that need more context
+3. **Poor structure** - Content organization issues
+4. **Missing context** - Assumptions about reader knowledge
+5. **Confusing language** - Jargon without explanation
+
+Suggest specific improvements for each issue.
+`
+  };
+
+  return baseInstructions + (focusInstructions[focus] || focusInstructions.comprehensive);
+}
+
+/**
+ * Format the complete review context for the LLM
+ * @param {string} styleGuide - Style guide content
+ * @param {string} instructions - Review instructions
+ * @param {string} content - Content to review
+ * @param {string} focus - Focus area
+ * @returns {string} Formatted review context
+ */
+function formatReviewContext(styleGuide, instructions, content, focus) {
+  return `${instructions}
+
+---
+
+# Style Guide Reference
+
+${styleGuide}
+
+---
+
+# Content to Review
+
+${content}
+
+---
+
+**Focus Area**: ${focus}
+
+Please provide your review above, organized by issue type with specific line/section references.
+`;
+}
+
+module.exports = {
+  reviewContent
+};