specweave 0.30.13 → 0.30.16

package/plugins/specweave-kafka/examples/n8n-workflow/kafka-to-slack.json

@@ -0,0 +1,50 @@
+{
+  "name": "Kafka to Slack Notification",
+  "nodes": [
+    {
+      "parameters": {
+        "topic": "user-events",
+        "brokers": "localhost:9092",
+        "groupId": "n8n-consumer"
+      },
+      "name": "Kafka Trigger",
+      "type": "n8n-nodes-base.kafkaTrigger",
+      "typeVersion": 1,
+      "position": [250, 300]
+    },
+    {
+      "parameters": {
+        "conditions": {
+          "string": [
+            {
+              "value1": "={{$json[\"event_type\"]}}",
+              "value2": "purchase"
+            }
+          ]
+        }
+      },
+      "name": "Filter Purchases",
+      "type": "n8n-nodes-base.if",
+      "typeVersion": 1,
+      "position": [450, 300]
+    },
+    {
+      "parameters": {
+        "channel": "#sales",
+        "text": "New purchase: {{$json[\"amount\"]}} from user {{$json[\"userId\"]}}"
+      },
+      "name": "Slack Notification",
+      "type": "n8n-nodes-base.slack",
+      "typeVersion": 1,
+      "position": [650, 300]
+    }
+  ],
+  "connections": {
+    "Kafka Trigger": {
+      "main": [[{"node": "Filter Purchases", "type": "main", "index": 0}]]
+    },
+    "Filter Purchases": {
+      "main": [[{"node": "Slack Notification", "type": "main", "index": 0}]]
+    }
+  }
+}

package/plugins/specweave-kafka/examples/simple-producer-consumer/.env.example

@@ -0,0 +1,15 @@
+# Kafka Configuration
+KAFKA_BROKERS=localhost:9092
+KAFKA_CLIENT_ID=simple-example
+KAFKA_TOPIC=demo-topic
+KAFKA_GROUP_ID=demo-group
+
+# For multiple brokers, use comma-separated list:
+# KAFKA_BROKERS=broker1:9092,broker2:9092,broker3:9092
+
+# For Confluent Cloud or secure clusters:
+# KAFKA_BROKERS=pkc-xxxxx.us-east-1.aws.confluent.cloud:9092
+# KAFKA_USERNAME=your-api-key
+# KAFKA_PASSWORD=your-api-secret
+# KAFKA_MECHANISM=plain
+# KAFKA_SSL=true

package/plugins/specweave-kafka/examples/simple-producer-consumer/README.md

@@ -0,0 +1,183 @@
+# Simple Producer-Consumer Example
+
+**Basic Kafka producer and consumer with Node.js**
+
+This example demonstrates the simplest way to produce and consume messages with Kafka using KafkaJS.
+
+## Prerequisites
+
+- Node.js 18+
+- Kafka cluster running (local or remote)
+- Broker accessible at `localhost:9092` (or update `.env`)
+
+## Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your Kafka broker addresses
+
+# Start Kafka locally (if needed)
+docker-compose up -d
+```
+
+## Run
+
+### Terminal 1: Start Consumer
+
+```bash
+npm run consumer
+```
+
+Expected output:
+```
+✓ Consumer connected to Kafka
+✓ Subscribed to topic: demo-topic
+⏳ Waiting for messages...
+
+📥 Received message:
+   Topic: demo-topic
+   Partition: 0
+   Offset: 0
+   Key: user-123
+   Value: {"message":"Hello Kafka!","timestamp":"2025-11-15T..."}
+```
+
+### Terminal 2: Send Messages
+
+```bash
+npm run producer
+```
+
+Expected output:
+```
+✓ Producer connected to Kafka
+📤 Sending message...
+✅ Message sent successfully!
+   Topic: demo-topic
+   Partition: 0
+   Offset: 0
+```
+
+## Files
+
+- **producer.js** - Sends a test message to Kafka
+- **consumer.js** - Consumes messages from Kafka topic
+- **package.json** - Dependencies and scripts
+- **.env.example** - Environment variables template
+- **docker-compose.yml** - Local Kafka cluster (optional)
+
+## Code Walkthrough
+
+### Producer (producer.js)
+
+```javascript
+const { Kafka } = require('kafkajs');
+
+// 1. Create Kafka client
+const kafka = new Kafka({
+  clientId: 'my-producer',
+  brokers: ['localhost:9092']
+});
+
+// 2. Create producer
+const producer = kafka.producer();
+
+// 3. Connect and send
+async function run() {
+  await producer.connect();
+
+  await producer.send({
+    topic: 'demo-topic',
+    messages: [{
+      key: 'user-123',
+      value: JSON.stringify({ message: 'Hello Kafka!', timestamp: new Date() })
+    }]
+  });
+
+  await producer.disconnect();
+}
+```
+
+### Consumer (consumer.js)
+
+```javascript
+const { Kafka } = require('kafkajs');
+
+// 1. Create Kafka client
+const kafka = new Kafka({
+  clientId: 'my-consumer',
+  brokers: ['localhost:9092']
+});
+
+// 2. Create consumer with group ID
+const consumer = kafka.consumer({ groupId: 'demo-group' });
+
+// 3. Subscribe and consume
+async function run() {
+  await consumer.connect();
+  await consumer.subscribe({ topic: 'demo-topic', fromBeginning: true });
+
+  await consumer.run({
+    eachMessage: async ({ topic, partition, message }) => {
+      console.log({
+        topic,
+        partition,
+        offset: message.offset,
+        key: message.key?.toString(),
+        value: message.value?.toString()
+      });
+    }
+  });
+}
+```
+
+## Troubleshooting
+
+### Error: Connection refused
+
+```bash
+# Check if Kafka is running
+docker ps | grep kafka
+
+# If not running, start it
+docker-compose up -d
+
+# Wait for Kafka to be ready (~30 seconds)
+docker logs kafka-broker -f
+```
+
+### Error: Topic does not exist
+
+```bash
+# Create topic manually
+kafka-topics --bootstrap-server localhost:9092 \
+  --create --topic demo-topic \
+  --partitions 3 --replication-factor 1
+```
+
+### Consumer not receiving messages
+
+```bash
+# Reset consumer group offsets
+kafka-consumer-groups --bootstrap-server localhost:9092 \
+  --group demo-group \
+  --topic demo-topic \
+  --reset-offsets --to-earliest \
+  --execute
+```
+
+## Next Steps
+
+- Try [avro-schema-registry](../avro-schema-registry/) - Add schema validation
+- Try [exactly-once-semantics](../exactly-once-semantics/) - Ensure zero message loss
+- Try [kafka-streams-app](../kafka-streams-app/) - Real-time stream processing
+
+## Documentation
+
+- [KafkaJS Documentation](https://kafka.js.org/)
+- [Apache Kafka Documentation](https://kafka.apache.org/documentation/)
+- [SpecWeave Getting Started Guide](../../.specweave/docs/public/guides/kafka-getting-started.md)

package/plugins/specweave-kafka/examples/simple-producer-consumer/consumer.js

@@ -0,0 +1,60 @@
+require('dotenv').config();
+const { Kafka } = require('kafkajs');
+
+const kafka = new Kafka({
+  clientId: process.env.KAFKA_CLIENT_ID || 'my-consumer',
+  brokers: (process.env.KAFKA_BROKERS || 'localhost:9092').split(',')
+});
+
+const consumer = kafka.consumer({
+  groupId: process.env.KAFKA_GROUP_ID || 'demo-group'
+});
+
+async function run() {
+  try {
+    // Connect consumer
+    await consumer.connect();
+    console.log('✓ Consumer connected to Kafka');
+
+    // Subscribe to topic
+    const topic = process.env.KAFKA_TOPIC || 'demo-topic';
+    await consumer.subscribe({ topic, fromBeginning: true });
+    console.log('✓ Subscribed to topic:', topic);
+    console.log('⏳ Waiting for messages...\n');
+
+    // Consume messages
+    await consumer.run({
+      eachMessage: async ({ topic, partition, message }) => {
+        console.log('📥 Received message:');
+        console.log('   Topic:', topic);
+        console.log('   Partition:', partition);
+        console.log('   Offset:', message.offset);
+        console.log('   Key:', message.key?.toString());
+        console.log('   Value:', message.value?.toString());
+
+        // Parse headers
+        if (message.headers) {
+          console.log('   Headers:');
+          Object.entries(message.headers).forEach(([key, value]) => {
+            console.log(`     ${key}:`, value.toString());
+          });
+        }
+
+        console.log(''); // Blank line between messages
+      }
+    });
+
+  } catch (error) {
+    console.error('❌ Error:', error);
+  }
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  console.log('\n⏸️  Shutting down consumer...');
+  await consumer.disconnect();
+  console.log('✓ Consumer disconnected');
+  process.exit(0);
+});
+
+run().catch(console.error);

package/plugins/specweave-kafka/examples/simple-producer-consumer/docker-compose.yml

@@ -0,0 +1,30 @@
+version: '3.8'
+
+services:
+  kafka-broker:
+    image: confluentinc/cp-kafka:7.5.0
+    hostname: kafka-broker
+    container_name: kafka-broker
+    ports:
+      - "9092:9092"
+      - "9101:9101"
+    environment:
+      KAFKA_NODE_ID: 1
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
+      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka-broker:29092,PLAINTEXT_HOST://localhost:9092'
+      KAFKA_PROCESS_ROLES: 'broker,controller'
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka-broker:29093'
+      KAFKA_LISTENERS: 'PLAINTEXT://kafka-broker:29092,CONTROLLER://kafka-broker:29093,PLAINTEXT_HOST://0.0.0.0:9092'
+      KAFKA_INTER_BROKER_LISTENER_NAME: 'PLAINTEXT'
+      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
+      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
+      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
+      KAFKA_JMX_PORT: 9101
+      KAFKA_JMX_HOSTNAME: localhost
+    volumes:
+      - kafka-data:/var/lib/kafka/data
+
+volumes:
+  kafka-data:
+    driver: local

package/plugins/specweave-kafka/examples/simple-producer-consumer/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "kafka-simple-producer-consumer",
+  "version": "1.0.0",
+  "description": "Simple Kafka producer and consumer example",
+  "main": "producer.js",
+  "scripts": {
+    "producer": "node producer.js",
+    "consumer": "node consumer.js",
+    "start": "npm run consumer"
+  },
+  "keywords": ["kafka", "producer", "consumer", "example"],
+  "author": "SpecWeave",
+  "license": "MIT",
+  "dependencies": {
+    "kafkajs": "^2.2.4",
+    "dotenv": "^16.3.1"
+  }
+}

package/plugins/specweave-kafka/examples/simple-producer-consumer/producer.js

@@ -0,0 +1,52 @@
+require('dotenv').config();
+const { Kafka } = require('kafkajs');
+
+const kafka = new Kafka({
+  clientId: process.env.KAFKA_CLIENT_ID || 'my-producer',
+  brokers: (process.env.KAFKA_BROKERS || 'localhost:9092').split(',')
+});
+
+const producer = kafka.producer();
+
+async function run() {
+  try {
+    // Connect producer
+    await producer.connect();
+    console.log('✓ Producer connected to Kafka');
+
+    // Prepare message
+    const message = {
+      message: 'Hello Kafka!',
+      timestamp: new Date().toISOString(),
+      source: 'simple-producer'
+    };
+
+    console.log('\n📤 Sending message...');
+
+    // Send message
+    const result = await producer.send({
+      topic: process.env.KAFKA_TOPIC || 'demo-topic',
+      messages: [{
+        key: 'user-123',
+        value: JSON.stringify(message),
+        headers: {
+          'correlation-id': '12345',
+          'content-type': 'application/json'
+        }
+      }]
+    });
+
+    console.log('✅ Message sent successfully!');
+    console.log('   Topic:', result[0].topicName);
+    console.log('   Partition:', result[0].partition);
+    console.log('   Offset:', result[0].baseOffset);
+
+  } catch (error) {
+    console.error('❌ Error:', error);
+  } finally {
+    await producer.disconnect();
+    console.log('\n✓ Producer disconnected');
+  }
+}
+
+run().catch(console.error);

package/plugins/specweave-release/commands/specweave-release-npm.md

@@ -318,9 +318,9 @@ Show the user:
 ## Direct Mode Safety Rules
 
 - ✅ ALWAYS rebuild before publishing (`npm run rebuild`)
-- ✅ Use `--only` for emergency/quick releases or local testing
-- ✅ Default mode (GitHub Actions) is preferred for regular releases
-- ✅ Direct mode gives immediate feedback (no CI wait time)
+- ✅ Use `--only` when you want to publish but push git later
+- ✅ Default mode (no flags) is preferred - auto-commits, publishes, and pushes
+- ✅ Direct mode gives control over git push timing
 - ⚠️ Remember to push git changes later to sync GitHub
 
 ## Success Criteria (Direct Mode)
@@ -415,7 +415,7 @@ Show the user:
 5. Publish: `npm publish --registry https://registry.npmjs.org`
 6. Push: `git push origin develop --follow-tags`
 
-**Or use**: `/specweave-release:npm --only --push` for full release
+**Or use**: `/specweave-release:npm` (no flags) for full instant release
 ```
 
 ## Local Mode Safety Rules

package/plugins/specweave-docs-preview/.claude-plugin/plugin.json

@@ -1,21 +0,0 @@
-{
-  "name": "specweave-docs-preview",
-  "description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
-  "version": "0.24.0",
-  "author": {
-    "name": "SpecWeave Team",
-    "url": "https://spec-weave.com"
-  },
-  "homepage": "https://spec-weave.com",
-  "repository": "https://github.com/anton-abyzov/specweave",
-  "license": "MIT",
-  "keywords": [
-    "docusaurus",
-    "documentation",
-    "preview",
-    "docs-server",
-    "hot-reload",
-    "static-site",
-    "specweave"
-  ]
-}