@redpanda-data/docs-extensions-and-macros 4.13.6 → 4.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.13.6",
+  "version": "4.14.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

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

@@ -1,196 +0,0 @@
-/**
- * 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
-};

package/bin/mcp-tools/frontmatter.js

@@ -1,138 +0,0 @@
-/**
- * Frontmatter Parser for MCP Prompts
- *
- * Parses YAML frontmatter from markdown files to extract metadata.
- * Supports validation against JSON schemas.
- */
-
-const yaml = require('js-yaml');
-
-/**
- * Parse frontmatter from markdown content
- * @param {string} content - Markdown content with optional frontmatter
- * @returns {{ metadata: Object, content: string }} Parsed frontmatter and remaining content
- */
-function parseFrontmatter(content) {
-  const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
-
-  if (!match) {
-    // No frontmatter found - return empty metadata and full content
-    return {
-      metadata: {},
-      content: content
-    };
-  }
-
-  try {
-    const metadata = yaml.load(match[1]) || {};
-    const remainingContent = match[2];
-
-    return {
-      metadata,
-      content: remainingContent
-    };
-  } catch (err) {
-    throw new Error(`Failed to parse YAML frontmatter: ${err.message}`);
-  }
-}
-
-/**
- * JSON Schema for prompt frontmatter
- */
-const promptFrontmatterSchema = {
-  type: 'object',
-  properties: {
-    description: {
-      type: 'string',
-      minLength: 10,
-      description: 'Description of what this prompt does'
-    },
-    version: {
-      type: 'string',
-      pattern: '^\\d+\\.\\d+\\.\\d+$',
-      description: 'Semantic version (for example, 1.0.0)'
-    },
-    arguments: {
-      type: 'array',
-      description: 'Arguments this prompt accepts',
-      items: {
-        type: 'object',
-        required: ['name', 'description', 'required'],
-        properties: {
-          name: {
-            type: 'string',
-            pattern: '^[a-z_][a-z0-9_]*$',
-            description: 'Argument name (lowercase, underscores allowed)'
-          },
-          description: {
-            type: 'string',
-            minLength: 5,
-            description: 'What this argument is for'
-          },
-          required: {
-            type: 'boolean',
-            description: 'Whether this argument is required'
-          }
-        },
-        additionalProperties: false
-      }
-    },
-    argumentFormat: {
-      type: 'string',
-      enum: ['content-append', 'structured'],
-      description: 'How to format arguments when building the prompt'
-    }
-  },
-  additionalProperties: false
-};
-
-/**
- * Validate frontmatter against schema
- * @param {Object} metadata - Parsed frontmatter metadata
- * @param {string} filename - File name (for error messages)
- * @param {Object} schema - JSON schema to validate against
- * @throws {Error} If validation fails
- */
-function validateFrontmatter(metadata, filename, schema = promptFrontmatterSchema) {
-  const Ajv = require('ajv');
-  const ajv = new Ajv({ allErrors: true });
-
-  const valid = ajv.validate(schema, metadata);
-
-  if (!valid) {
-    const errors = ajv.errors.map(err => {
-      const path = err.instancePath || 'root';
-      return `  - ${path}: ${err.message}`;
-    }).join('\n');
-
-    throw new Error(`Invalid frontmatter in ${filename}:\n${errors}`);
-  }
-}
-
-/**
- * Parse and validate prompt file
- * @param {string} content - File content
- * @param {string} filename - File name
- * @returns {{ metadata: Object, content: string }} Validated metadata and content
- */
-function parsePromptFile(content, filename) {
-  const { metadata, content: promptContent } = parseFrontmatter(content);
-
-  // If metadata exists, validate it
-  if (Object.keys(metadata).length > 0) {
-    validateFrontmatter(metadata, filename);
-  }
-
-  return {
-    metadata,
-    content: promptContent
-  };
-}
-
-module.exports = {
-  parseFrontmatter,
-  parsePromptFile,
-  validateFrontmatter,
-  promptFrontmatterSchema
-};

package/bin/mcp-tools/prompt-discovery.js

@@ -1,283 +0,0 @@
-/**
- * Prompt Discovery and Caching
- *
- * Automatically discovers prompts from the mcp/prompts directory.
- * Caches prompt content and metadata for performance.
- * Supports file watching in development mode.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { parsePromptFile, validateFrontmatter } = require('./frontmatter');
-const { validatePromptName } = require('./mcp-validation');
-
-/**
- * In-memory prompt cache
- */
-class PromptCache {
-  constructor() {
-    this.prompts = new Map(); // name -> { metadata, content, filePath }
-    this.watchers = [];
-  }
-
-  /**
-   * Set prompt in cache
-   * @param {string} name - Prompt name
-   * @param {Object} data - Prompt data
-   */
-  set(name, data) {
-    this.prompts.set(name, data);
-  }
-
-  /**
-   * Get prompt from cache
-   * @param {string} name - Prompt name
-   * @returns {Object|null} Prompt data or null
-   */
-  get(name) {
-    return this.prompts.get(name) || null;
-  }
-
-  /**
-   * Get all prompts
-   * @returns {Array} Array of prompt objects
-   */
-  getAll() {
-    return Array.from(this.prompts.values());
-  }
-
-  /**
-   * Get all prompt names
-   * @returns {Array} Array of prompt names
-   */
-  getNames() {
-    return Array.from(this.prompts.keys());
-  }
-
-  /**
-   * Check if prompt exists
-   * @param {string} name - Prompt name
-   * @returns {boolean}
-   */
-  has(name) {
-    return this.prompts.has(name);
-  }
-
-  /**
-   * Clear all prompts
-   */
-  clear() {
-    this.prompts.clear();
-  }
-
-  /**
-   * Stop all file watchers
-   */
-  stopWatching() {
-    this.watchers.forEach(watcher => watcher.close());
-    this.watchers = [];
-  }
-
-  /**
-   * Add a file watcher
-   * @param {FSWatcher} watcher - File system watcher
-   */
-  addWatcher(watcher) {
-    this.watchers.push(watcher);
-  }
-}
-
-/**
- * Default argument formatters for different types
- */
-const argumentFormatters = {
-  'content-append': (args, schema) => {
-    if (!args) return '';
-
-    let result = '\n\n---\n\n';
-
-    // If there's a 'content' argument, add it specially
-    if (args.content) {
-      result += `**Content to review:**\n\n${args.content}`;
-      return result;
-    }
-
-    // Otherwise, format all arguments
-    Object.entries(args).forEach(([key, value]) => {
-      const argDef = schema?.find(a => a.name === key);
-      const label = argDef?.name || key;
-      result += `**${label.charAt(0).toUpperCase() + label.slice(1)}:** ${value}\n`;
-    });
-
-    return result;
-  },
-
-  'structured': (args, schema) => {
-    if (!args) return '';
-
-    let result = '\n\n---\n\n';
-    Object.entries(args).forEach(([key, value]) => {
-      result += `**${key}:** ${value}\n`;
-    });
-
-    return result;
-  }
-};
-
-/**
- * Discover all prompts in the prompts directory
- * @param {string} promptsDir - Path to prompts directory
- * @returns {Array} Array of discovered prompts
- */
-function discoverPrompts(promptsDir) {
-  if (!fs.existsSync(promptsDir)) {
-    throw new Error(`Prompts directory not found: ${promptsDir}`);
-  }
-
-  const files = fs.readdirSync(promptsDir).filter(f => f.endsWith('.md'));
-  const prompts = [];
-
-  for (const file of files) {
-    try {
-      const name = path.basename(file, '.md');
-      validatePromptName(name); // Ensure safe name
-
-      const filePath = path.join(promptsDir, file);
-      const fileContent = fs.readFileSync(filePath, 'utf8');
-
-      const { metadata, content } = parsePromptFile(fileContent, file);
-
-      // Build prompt object
-      const prompt = {
-        name,
-        description: metadata.description || `Prompt: ${name}`,
-        version: metadata.version || '1.0.0',
-        arguments: metadata.arguments || [],
-        argumentFormat: metadata.argumentFormat || 'content-append',
-        content,
-        filePath,
-        _rawMetadata: metadata
-      };
-
-      prompts.push(prompt);
-    } catch (err) {
-      console.error(`Error loading prompt ${file}: ${err.message}`);
-      // Continue loading other prompts
-    }
-  }
-
-  return prompts;
-}
-
-/**
- * Load all prompts into cache
- * @param {string} baseDir - Base directory (repo root)
- * @param {PromptCache} cache - Prompt cache instance
- * @returns {Array} Loaded prompts
- */
-function loadAllPrompts(baseDir, cache) {
-  const promptsDir = path.join(baseDir, 'mcp', 'prompts');
-  const prompts = discoverPrompts(promptsDir);
-
-  // Clear and reload cache
-  cache.clear();
-
-  prompts.forEach(prompt => {
-    cache.set(prompt.name, prompt);
-  });
-
-  return prompts;
-}
-
-/**
- * Watch prompts directory for changes (development mode)
- * @param {string} baseDir - Base directory
- * @param {PromptCache} cache - Prompt cache instance
- * @param {Function} onChange - Callback when prompts change
- */
-function watchPrompts(baseDir, cache, onChange) {
-  const promptsDir = path.join(baseDir, 'mcp', 'prompts');
-
-  if (!fs.existsSync(promptsDir)) {
-    console.error(`Cannot watch prompts directory (not found): ${promptsDir}`);
-    return;
-  }
-
-  const watcher = fs.watch(promptsDir, (eventType, filename) => {
-    if (!filename || !filename.endsWith('.md')) {
-      return;
-    }
-
-    console.error(`Prompt file changed: ${filename} (${eventType})`);
-    console.error('Reloading all prompts...');
-
-    try {
-      const prompts = loadAllPrompts(baseDir, cache);
-      console.error(`Reloaded ${prompts.length} prompts`);
-
-      if (onChange) {
-        onChange(prompts);
-      }
-    } catch (err) {
-      console.error(`Error reloading prompts: ${err.message}`);
-    }
-  });
-
-  cache.addWatcher(watcher);
-  console.error('File watching enabled for prompts (dev mode)');
-}
-
-/**
- * Build prompt text with arguments
- * @param {Object} prompt - Prompt object from cache
- * @param {Object} args - Arguments provided by user
- * @returns {string} Complete prompt text
- */
-function buildPromptWithArguments(prompt, args) {
-  let promptText = prompt.content;
-
-  if (!args || Object.keys(args).length === 0) {
-    return promptText;
-  }
-
-  // Use the formatter specified by the prompt
-  const formatter = argumentFormatters[prompt.argumentFormat];
-  if (!formatter) {
-    console.error(
-      `Unknown argument format: ${prompt.argumentFormat} for prompt ${prompt.name}`
-    );
-    return promptText;
-  }
-
-  const formattedArgs = formatter(args, prompt.arguments);
-  promptText += formattedArgs;
-
-  return promptText;
-}
-
-/**
- * Convert prompts to MCP protocol format
- * @param {Array} prompts - Discovered prompts
- * @returns {Array} Prompts in MCP format
- */
-function promptsToMcpFormat(prompts) {
-  return prompts.map(prompt => ({
-    name: prompt.name,
-    description: prompt.description,
-    arguments: prompt.arguments.map(arg => ({
-      name: arg.name,
-      description: arg.description,
-      required: arg.required
-    }))
-  }));
-}
-
-module.exports = {
-  PromptCache,
-  discoverPrompts,
-  loadAllPrompts,
-  watchPrompts,
-  buildPromptWithArguments,
-  promptsToMcpFormat,
-  argumentFormatters
-};