specweave 0.18.1 → 0.20.0

package/plugins/specweave-kafka/lib/documentation/topology-generator.ts

@@ -0,0 +1,290 @@
+/**
+ * Topology Generator
+ *
+ * Generates cluster topology documentation from Kafka metadata
+ *
+ * @module topology-generator
+ */
+
+import { Admin } from 'kafkajs';
+
+/**
+ * Broker Metadata
+ */
+export interface BrokerMetadata {
+  /** Broker ID */
+  nodeId: number;
+  /** Hostname */
+  host: string;
+  /** Port */
+  port: number;
+  /** Rack ID (optional) */
+  rack?: string;
+}
+
+/**
+ * Topic Metadata
+ */
+export interface TopicMetadata {
+  /** Topic name */
+  name: string;
+  /** Number of partitions */
+  partitions: number;
+  /** Replication factor */
+  replicationFactor: number;
+  /** Topic configurations */
+  configs: Record<string, string>;
+  /** Is internal topic? */
+  isInternal: boolean;
+}
+
+/**
+ * Partition Details
+ */
+export interface PartitionDetails {
+  /** Topic name */
+  topic: string;
+  /** Partition ID */
+  partition: number;
+  /** Leader broker ID */
+  leader: number;
+  /** In-sync replicas */
+  isr: number[];
+  /** All replicas */
+  replicas: number[];
+}
+
+/**
+ * Cluster Topology
+ */
+export interface ClusterTopology {
+  /** Cluster ID */
+  clusterId: string;
+  /** Controller broker ID */
+  controller: number;
+  /** Brokers */
+  brokers: BrokerMetadata[];
+  /** Topics */
+  topics: TopicMetadata[];
+  /** Total partitions */
+  totalPartitions: number;
+  /** Under-replicated partitions */
+  underReplicatedPartitions: PartitionDetails[];
+  /** Generated timestamp */
+  generatedAt: Date;
+}
+
+/**
+ * Topology Generator
+ *
+ * Extracts and formats Kafka cluster topology information
+ */
+export class TopologyGenerator {
+  /**
+   * Generate cluster topology documentation
+   */
+  static async generate(admin: Admin): Promise<ClusterTopology> {
+    // Get cluster metadata
+    const cluster = await admin.describeCluster();
+
+    // Get all topics
+    const allTopics = await admin.listTopics();
+
+    // Get topic metadata
+    const topicMetadata = await admin.fetchTopicMetadata({ topics: allTopics });
+
+    // Get topic configurations
+    const topicConfigs = await admin.fetchTopicOffsets(allTopics.slice(0, 10)); // Sample
+
+    // Extract topics
+    const topics: TopicMetadata[] = [];
+    let totalPartitions = 0;
+    const underReplicatedPartitions: PartitionDetails[] = [];
+
+    for (const topicData of topicMetadata.topics) {
+      const partitionCount = topicData.partitions.length;
+      totalPartitions += partitionCount;
+
+      // Calculate replication factor (from first partition)
+      const replicationFactor =
+        topicData.partitions.length > 0 ? topicData.partitions[0].replicas.length : 0;
+
+      topics.push({
+        name: topicData.name,
+        partitions: partitionCount,
+        replicationFactor,
+        configs: {}, // Would fetch from describeConfigs in real implementation
+        isInternal: topicData.name.startsWith('__') || topicData.name.startsWith('_'),
+      });
+
+      // Detect under-replicated partitions
+      for (const partition of topicData.partitions) {
+        if (partition.isr.length < partition.replicas.length) {
+          underReplicatedPartitions.push({
+            topic: topicData.name,
+            partition: partition.partitionId,
+            leader: partition.leader,
+            isr: partition.isr.map(Number),
+            replicas: partition.replicas.map(Number),
+          });
+        }
+      }
+    }
+
+    // Build topology
+    const topology: ClusterTopology = {
+      clusterId: cluster.clusterId,
+      controller: Number(cluster.controller),
+      brokers: cluster.brokers.map((broker) => ({
+        nodeId: broker.nodeId,
+        host: broker.host,
+        port: broker.port,
+        rack: broker.rack,
+      })),
+      topics,
+      totalPartitions,
+      underReplicatedPartitions,
+      generatedAt: new Date(),
+    };
+
+    return topology;
+  }
+
+  /**
+   * Format topology as Markdown
+   */
+  static formatAsMarkdown(topology: ClusterTopology): string {
+    const lines: string[] = [];
+
+    lines.push('# Kafka Cluster Topology');
+    lines.push('');
+    lines.push(`**Cluster ID**: ${topology.clusterId}`);
+    lines.push(`**Controller**: Broker ${topology.controller}`);
+    lines.push(`**Generated**: ${topology.generatedAt.toISOString()}`);
+    lines.push('');
+
+    // Brokers section
+    lines.push('## Brokers');
+    lines.push('');
+    lines.push('| Broker ID | Host | Port | Rack |');
+    lines.push('|-----------|------|------|------|');
+    for (const broker of topology.brokers) {
+      lines.push(
+        `| ${broker.nodeId} | ${broker.host} | ${broker.port} | ${broker.rack || 'N/A'} |`
+      );
+    }
+    lines.push('');
+
+    // Topics section
+    lines.push('## Topics');
+    lines.push('');
+    lines.push(`**Total Topics**: ${topology.topics.length}`);
+    lines.push(`**Total Partitions**: ${topology.totalPartitions}`);
+    lines.push('');
+    lines.push('### Topic List');
+    lines.push('');
+    lines.push('| Topic Name | Partitions | Replication Factor | Internal |');
+    lines.push('|------------|------------|-------------------|----------|');
+
+    // Sort topics by name
+    const sortedTopics = [...topology.topics].sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const topic of sortedTopics) {
+      lines.push(
+        `| ${topic.name} | ${topic.partitions} | ${topic.replicationFactor} | ${topic.isInternal ? 'Yes' : 'No'} |`
+      );
+    }
+    lines.push('');
+
+    // Under-replicated partitions section
+    if (topology.underReplicatedPartitions.length > 0) {
+      lines.push('## ⚠️  Under-Replicated Partitions');
+      lines.push('');
+      lines.push('| Topic | Partition | Leader | ISR | Replicas |');
+      lines.push('|-------|-----------|--------|-----|----------|');
+
+      for (const partition of topology.underReplicatedPartitions) {
+        lines.push(
+          `| ${partition.topic} | ${partition.partition} | ${partition.leader} | ${partition.isr.join(', ')} | ${partition.replicas.join(', ')} |`
+        );
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Format topology as JSON
+   */
+  static formatAsJSON(topology: ClusterTopology): string {
+    return JSON.stringify(topology, null, 2);
+  }
+
+  /**
+   * Generate Mermaid diagram for cluster topology
+   */
+  static generateMermaidDiagram(topology: ClusterTopology): string {
+    const lines: string[] = [];
+
+    lines.push('```mermaid');
+    lines.push('graph TB');
+    lines.push('    subgraph Kafka Cluster');
+
+    // Brokers
+    for (const broker of topology.brokers) {
+      const isController = broker.nodeId === topology.controller;
+      const shape = isController ? '[Broker ' : '(Broker ';
+      const endShape = isController ? ']' : ')';
+      lines.push(
+        `        B${broker.nodeId}${shape}${broker.nodeId}<br/>${broker.host}:${broker.port}${endShape}`
+      );
+    }
+
+    // Topics (sample - limit to 10 for readability)
+    const sampleTopics = topology.topics.filter((t) => !t.isInternal).slice(0, 10);
+
+    for (const topic of sampleTopics) {
+      const topicId = topic.name.replace(/[^a-zA-Z0-9]/g, '_');
+      lines.push(`        T_${topicId}[${topic.name}<br/>${topic.partitions} partitions]`);
+
+      // Connect topic to brokers (simplified)
+      for (const broker of topology.brokers.slice(0, 3)) {
+        lines.push(`        T_${topicId} --> B${broker.nodeId}`);
+      }
+    }
+
+    lines.push('    end');
+    lines.push('```');
+
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Example Usage: Generate Topology Documentation
+ *
+ * ```typescript
+ * import { Kafka } from 'kafkajs';
+ * import { TopologyGenerator } from './topology-generator';
+ *
+ * const kafka = new Kafka({ brokers: ['localhost:9092'] });
+ * const admin = kafka.admin();
+ * await admin.connect();
+ *
+ * // Generate topology
+ * const topology = await TopologyGenerator.generate(admin);
+ *
+ * // Format as Markdown
+ * const markdown = TopologyGenerator.formatAsMarkdown(topology);
+ * console.log(markdown);
+ *
+ * // Generate Mermaid diagram
+ * const diagram = TopologyGenerator.generateMermaidDiagram(topology);
+ * console.log(diagram);
+ *
+ * await admin.disconnect();
+ * ```
+ */
+
+export default TopologyGenerator;

package/plugins/specweave-kafka/lib/mcp/detector.js

@@ -0,0 +1,298 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import {
+  MCPServerType,
+  AuthMethod
+} from "./types";
+const execAsync = promisify(exec);
+class MCPServerDetector {
+  /**
+   * Detect all available MCP servers
+   */
+  async detectAll() {
+    const servers = [];
+    const checks = [
+      this.detectKanapuli(),
+      this.detectTuannvm(),
+      this.detectJoelHanson(),
+      this.detectConfluent()
+    ];
+    const results = await Promise.allSettled(checks);
+    results.forEach((result) => {
+      if (result.status === "fulfilled" && result.value) {
+        servers.push(result.value);
+      }
+    });
+    const recommended = this.rankServers(servers);
+    return {
+      servers,
+      recommended: recommended?.type || null,
+      rankingReason: this.getRankingReason(recommended, servers)
+    };
+  }
+  /**
+   * Detect kanapuli/mcp-kafka server
+   */
+  async detectKanapuli() {
+    try {
+      const { stdout } = await execAsync('npm list -g mcp-kafka --json 2>/dev/null || echo "{}"');
+      const packageInfo = JSON.parse(stdout);
+      const installed = !!packageInfo.dependencies?.["mcp-kafka"];
+      if (!installed) {
+        return {
+          type: MCPServerType.KANAPULI,
+          version: "unknown",
+          installed: false,
+          running: false,
+          capabilities: this.getKanapuliCapabilities()
+        };
+      }
+      const running = await this.isProcessRunning("mcp-kafka");
+      const version = packageInfo.dependencies?.["mcp-kafka"]?.version || "unknown";
+      return {
+        type: MCPServerType.KANAPULI,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getKanapuliCapabilities(),
+        connectionDetails: running ? {
+          host: "localhost",
+          port: 3e3,
+          // Default MCP port
+          protocol: "http",
+          healthEndpoint: "/health",
+          infoEndpoint: "/info"
+        } : void 0
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Detect tuannvm/kafka-mcp-server (Go implementation)
+   */
+  async detectTuannvm() {
+    try {
+      const { stdout } = await execAsync('which kafka-mcp-server 2>/dev/null || echo ""');
+      const installed = !!stdout.trim();
+      if (!installed) {
+        return {
+          type: MCPServerType.TUANNVM,
+          version: "unknown",
+          installed: false,
+          running: false,
+          capabilities: this.getTuannvmCapabilities()
+        };
+      }
+      const running = await this.isProcessRunning("kafka-mcp-server");
+      let version = "unknown";
+      try {
+        const { stdout: versionOut } = await execAsync("kafka-mcp-server --version 2>/dev/null");
+        version = versionOut.trim();
+      } catch {
+      }
+      return {
+        type: MCPServerType.TUANNVM,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getTuannvmCapabilities(),
+        connectionDetails: running ? {
+          host: "localhost",
+          port: 8080,
+          // Default port
+          protocol: "http"
+        } : void 0
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Detect Joel-hanson/kafka-mcp-server
+   */
+  async detectJoelHanson() {
+    try {
+      const { stdout } = await execAsync('pip show kafka-mcp-server 2>/dev/null || echo ""');
+      const installed = stdout.includes("Name: kafka-mcp-server");
+      if (!installed) {
+        return {
+          type: MCPServerType.JOEL_HANSON,
+          version: "unknown",
+          installed: false,
+          running: false,
+          capabilities: this.getJoelHansonCapabilities()
+        };
+      }
+      const versionMatch = stdout.match(/Version: ([\d.]+)/);
+      const version = versionMatch ? versionMatch[1] : "unknown";
+      const running = await this.isProcessRunning("kafka-mcp-server");
+      return {
+        type: MCPServerType.JOEL_HANSON,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getJoelHansonCapabilities(),
+        connectionDetails: running ? {
+          host: "localhost",
+          port: 5e3,
+          // Default Python MCP port
+          protocol: "http"
+        } : void 0
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Detect Confluent official MCP server
+   */
+  async detectConfluent() {
+    try {
+      const { stdout } = await execAsync('confluent version 2>/dev/null || echo ""');
+      const installed = !!stdout.trim();
+      if (!installed) {
+        return {
+          type: MCPServerType.CONFLUENT,
+          version: "unknown",
+          installed: false,
+          running: false,
+          capabilities: this.getConfluentCapabilities()
+        };
+      }
+      const versionMatch = stdout.match(/Version:\s+([\d.]+)/);
+      const version = versionMatch ? versionMatch[1] : "unknown";
+      let running = false;
+      try {
+        const { stdout: authOut } = await execAsync("confluent auth current 2>/dev/null");
+        running = authOut.includes("Logged in as");
+      } catch {
+      }
+      return {
+        type: MCPServerType.CONFLUENT,
+        version,
+        installed: true,
+        running,
+        capabilities: this.getConfluentCapabilities()
+      };
+    } catch (error) {
+      return null;
+    }
+  }
+  /**
+   * Check if process is running
+   */
+  async isProcessRunning(processName) {
+    try {
+      const { stdout } = await execAsync(`ps aux | grep "${processName}" | grep -v grep || echo ""`);
+      return !!stdout.trim();
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Rank servers by priority (Confluent > tuannvm > kanapuli > Joel-hanson)
+   */
+  rankServers(servers) {
+    const ranking = [
+      MCPServerType.CONFLUENT,
+      MCPServerType.TUANNVM,
+      MCPServerType.KANAPULI,
+      MCPServerType.JOEL_HANSON
+    ];
+    for (const type of ranking) {
+      const server = servers.find((s) => s.type === type && s.installed);
+      if (server) return server;
+    }
+    return null;
+  }
+  /**
+   * Get ranking reason
+   */
+  getRankingReason(recommended, servers) {
+    if (!recommended) {
+      return "No MCP servers installed";
+    }
+    const reasons = {
+      [MCPServerType.CONFLUENT]: "Confluent official MCP (best features: natural language, Flink SQL)",
+      [MCPServerType.TUANNVM]: "Go implementation (advanced SASL: SCRAM-SHA-256/512)",
+      [MCPServerType.KANAPULI]: "Node.js implementation (basic operations, SASL_PLAINTEXT)",
+      [MCPServerType.JOEL_HANSON]: "Python implementation (Claude Desktop integration)"
+    };
+    return reasons[recommended.type];
+  }
+  /**
+   * Get capabilities for each MCP server type
+   */
+  getKanapuliCapabilities() {
+    return {
+      authentication: [AuthMethod.SASL_PLAINTEXT, AuthMethod.PLAINTEXT],
+      operations: ["produce", "consume", "list-topics", "describe-topic", "get-offsets"],
+      advancedFeatures: []
+    };
+  }
+  getTuannvmCapabilities() {
+    return {
+      authentication: [
+        AuthMethod.SASL_SCRAM_SHA_256,
+        AuthMethod.SASL_SCRAM_SHA_512,
+        AuthMethod.SASL_PLAINTEXT,
+        AuthMethod.SASL_SSL,
+        AuthMethod.PLAINTEXT
+      ],
+      operations: [
+        "produce",
+        "consume",
+        "list-topics",
+        "create-topic",
+        "delete-topic",
+        "describe-topic",
+        "list-consumer-groups",
+        "describe-consumer-group",
+        "get-offsets",
+        "reset-offsets"
+      ],
+      advancedFeatures: ["consumer-group-management", "offset-management"]
+    };
+  }
+  getJoelHansonCapabilities() {
+    return {
+      authentication: [AuthMethod.SASL_PLAINTEXT, AuthMethod.PLAINTEXT, AuthMethod.SSL],
+      operations: ["produce", "consume", "list-topics", "describe-topic"],
+      advancedFeatures: ["claude-desktop-integration"]
+    };
+  }
+  getConfluentCapabilities() {
+    return {
+      authentication: [
+        AuthMethod.OAUTH,
+        AuthMethod.SASL_SCRAM_SHA_256,
+        AuthMethod.SASL_SCRAM_SHA_512,
+        AuthMethod.SASL_SSL
+      ],
+      operations: [
+        "produce",
+        "consume",
+        "list-topics",
+        "create-topic",
+        "delete-topic",
+        "describe-topic",
+        "list-consumer-groups",
+        "describe-consumer-group",
+        "schema-registry-operations",
+        "ksqldb-query",
+        "flink-sql-query"
+      ],
+      advancedFeatures: [
+        "natural-language-interface",
+        "schema-registry",
+        "ksqldb",
+        "flink-sql",
+        "cloud-managed"
+      ]
+    };
+  }
+}
+export {
+  MCPServerDetector
+};