@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/claude-code/events-message-queue/SKILL.md

@@ -0,0 +1,190 @@
+# Events: Message Queue
+
+> Use message queues for reliable async delivery with competing consumers and dead letter queues.
+
+## When to Use
+
+- You need reliable, at-least-once delivery — messages must not be lost even if the consumer crashes
+- You have work that should be processed by exactly one consumer (competing consumers pattern)
+- You need decoupling between producer and consumer throughput
+- You want dead letter queues (DLQ) for failed message handling
+- Background job processing, email sending, report generation, order fulfillment
+
+## Instructions
+
+**BullMQ (Redis-backed queue — recommended for Node.js):**
+
+```typescript
+import { Queue, Worker, Job } from 'bullmq';
+import { Redis } from 'ioredis';
+
+const connection = new Redis({ host: 'localhost', port: 6379 });
+
+// Define job data types
+interface SendEmailJobData {
+  to: string;
+  subject: string;
+  body: string;
+  templateId?: string;
+}
+
+// Producer — enqueue jobs
+const emailQueue = new Queue<SendEmailJobData>('email', { connection });
+
+async function scheduleWelcomeEmail(userId: string, email: string): Promise<void> {
+  await emailQueue.add(
+    'welcome',
+    { to: email, subject: 'Welcome!', body: 'Thanks for joining.', templateId: 'welcome-v2' },
+    {
+      delay: 5_000, // wait 5s before processing
+      attempts: 3, // retry up to 3 times
+      backoff: { type: 'exponential', delay: 2_000 }, // 2s, 4s, 8s
+      removeOnComplete: { count: 100 }, // keep last 100 completed jobs
+      removeOnFail: { count: 50 }, // keep last 50 failed jobs
+    }
+  );
+}
+
+// Consumer — process jobs
+const emailWorker = new Worker<SendEmailJobData>(
+  'email',
+  async (job: Job<SendEmailJobData>) => {
+    console.log(`Processing job ${job.id}: send email to ${job.data.to}`);
+    await sendEmail(job.data.to, job.data.subject, job.data.body);
+    // Returning from the processor marks the job complete
+  },
+  {
+    connection,
+    concurrency: 5, // process 5 jobs in parallel
+  }
+);
+
+emailWorker.on('completed', (job) => {
+  console.log(`Job ${job.id} completed`);
+});
+
+emailWorker.on('failed', (job, err) => {
+  console.error(`Job ${job?.id} failed after all retries:`, err.message);
+  // At this point, job moves to the failed set (acts as DLQ)
+});
+```
+
+**RabbitMQ with amqplib:**
+
+```typescript
+import amqp from 'amqplib';
+
+const QUEUE = 'order.processing';
+const DLQ = 'order.processing.dlq';
+
+async function setupQueue(): Promise<void> {
+  const conn = await amqp.connect('amqp://localhost');
+  const channel = await conn.createChannel();
+
+  // Dead letter queue
+  await channel.assertQueue(DLQ, { durable: true });
+
+  // Main queue with DLQ routing
+  await channel.assertQueue(QUEUE, {
+    durable: true,
+    arguments: {
+      'x-dead-letter-exchange': '',
+      'x-dead-letter-routing-key': DLQ,
+      'x-message-ttl': 3_600_000, // messages expire after 1h
+    },
+  });
+
+  channel.prefetch(1); // process one message at a time per consumer
+  return channel;
+}
+
+// Producer
+async function publishOrder(orderId: string, amount: number): Promise<void> {
+  const channel = await setupQueue();
+  const message = JSON.stringify({ orderId, amount, timestamp: new Date() });
+  channel.sendToQueue(QUEUE, Buffer.from(message), { persistent: true });
+}
+
+// Consumer
+async function startConsumer(): Promise<void> {
+  const channel = await setupQueue();
+  await channel.consume(QUEUE, async (msg) => {
+    if (!msg) return;
+    try {
+      const data = JSON.parse(msg.content.toString());
+      await processOrder(data.orderId, data.amount);
+      channel.ack(msg); // acknowledge on success
+    } catch (err) {
+      console.error('Processing failed:', err);
+      // nack with requeue=false — sends to DLQ after retries exhausted
+      channel.nack(msg, false, false);
+    }
+  });
+}
+```
+
+**Competing consumers pattern:**
+
+```typescript
+// Run multiple workers — each message processed by exactly ONE worker
+// Scale by adding more worker instances
+
+// Worker 1 (process 1)
+const worker1 = new Worker('orders', processOrder, { connection, concurrency: 3 });
+
+// Worker 2 (process 2 or separate machine)
+const worker2 = new Worker('orders', processOrder, { connection, concurrency: 3 });
+
+// BullMQ guarantees only one worker processes each job
+```
+
+## Details
+
+**Delivery guarantees:**
+
+- **At-most-once:** Fire and forget. Publisher sends, never tracks. Simple but messages can be lost.
+- **At-least-once:** Publisher gets confirmation; consumer acks after processing. May process twice — handlers must be idempotent.
+- **Exactly-once:** At-least-once + deduplication. Hard to achieve; usually simulated with idempotency keys.
+
+**Dead letter queue strategy:**
+
+1. Job fails after all retries
+2. Moved to DLQ automatically
+3. Monitoring alerts on DLQ depth
+4. Operators inspect, fix the bug, and replay from DLQ
+
+**Anti-patterns:**
+
+- Consumers that ack before processing (risk losing work on crash)
+- Long-running consumers without heartbeats (broker requeues "stalled" jobs)
+- Unbounded queue depth (apply backpressure via rate limiting producers)
+- Processing heavy jobs in HTTP request handlers (enqueue them instead)
+
+**Monitoring queues:**
+
+```typescript
+// BullMQ — check queue health
+const counts = await emailQueue.getJobCounts('waiting', 'active', 'completed', 'failed', 'delayed');
+console.log(counts);
+// Expose as /metrics endpoint for Prometheus
+```
+
+## Source
+
+microservices.io/patterns/communication-style/messaging.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/events-message-queue/skill.yaml

@@ -0,0 +1,43 @@
+name: events-message-queue
+version: "1.0.0"
+description: Use message queues for reliable async delivery with competing consumers and dead letter queues
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/events/**"
+  - "**/queues/**"
+  - "**/handlers/**"
+  - "**/socket/**"
+  - "**/pub-sub/**"
+related_skills:
+  - events-pubsub-pattern
+  - events-idempotency
+  - events-kafka-patterns
+stack_signals:
+  - nodejs
+  - typescript
+  - kafka
+  - redis
+  - rabbitmq
+keywords:
+  - message-queue
+  - at-least-once
+  - competing-consumers
+  - dead-letter-queue
+  - async-messaging
+metadata:
+  author: community
+  upstream: microservices.io/patterns/communication-style/messaging.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/events-outbox-pattern/SKILL.md

@@ -0,0 +1,212 @@
+# Events: Outbox Pattern
+
+> Reliably publish domain events using the transactional outbox and CDC polling approach.
+
+## When to Use
+
+- You need to guarantee that domain events are published whenever a database transaction commits
+- You can't afford to lose events (payment processed, order created, user registered)
+- You want to avoid the dual-write problem: "write to DB and publish to queue atomically"
+- You're building event-sourced systems or microservices with eventual consistency
+
+## Instructions
+
+**The problem the outbox solves:**
+
+```
+BAD:
+1. Write to DB ✓
+2. Publish to Kafka ✗  ← crash here → event lost, DB and queue out of sync
+
+GOOD (outbox):
+1. Write to DB + write to outbox table (one transaction) ✓
+2. Separate poller reads outbox, publishes to Kafka ✓
+3. Mark outbox records as published ✓
+```
+
+**Outbox table schema (SQL):**
+
+```sql
+CREATE TABLE outbox (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  event_type  TEXT NOT NULL,
+  payload     JSONB NOT NULL,
+  aggregate_id TEXT NOT NULL,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  published_at TIMESTAMPTZ,
+  publish_attempts INT NOT NULL DEFAULT 0,
+  error       TEXT
+);
+
+CREATE INDEX outbox_unpublished ON outbox (created_at)
+  WHERE published_at IS NULL;
+```
+
+**Write to DB + outbox in one transaction (Prisma example):**
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function createOrder(data: CreateOrderInput): Promise<Order> {
+  return prisma.$transaction(async (tx) => {
+    // Primary write
+    const order = await tx.order.create({
+      data: {
+        userId: data.userId,
+        items: data.items,
+        status: 'PENDING',
+        total: calculateTotal(data.items),
+      },
+    });
+
+    // Outbox write — same transaction
+    await tx.outbox.create({
+      data: {
+        eventType: 'order.created',
+        aggregateId: order.id,
+        payload: {
+          orderId: order.id,
+          userId: order.userId,
+          total: order.total,
+          items: order.items,
+          occurredAt: new Date().toISOString(),
+        },
+      },
+    });
+
+    return order;
+  });
+  // If transaction commits: both writes succeed atomically
+  // If transaction rolls back: neither write happens
+}
+```
+
+**Polling publisher (separate process):**
+
+```typescript
+class OutboxPublisher {
+  private running = false;
+
+  constructor(
+    private readonly db: PrismaClient,
+    private readonly producer: KafkaProducer,
+    private readonly pollIntervalMs = 1_000,
+    private readonly batchSize = 100
+  ) {}
+
+  start(): void {
+    this.running = true;
+    this.poll();
+  }
+
+  stop(): void {
+    this.running = false;
+  }
+
+  private async poll(): Promise<void> {
+    while (this.running) {
+      try {
+        await this.publishBatch();
+      } catch (err) {
+        console.error('Outbox poll error:', err);
+      }
+      await new Promise((r) => setTimeout(r, this.pollIntervalMs));
+    }
+  }
+
+  private async publishBatch(): Promise<void> {
+    // Fetch unpublished events — oldest first, batch
+    const events = await this.db.outbox.findMany({
+      where: { publishedAt: null, publishAttempts: { lt: 5 } },
+      orderBy: { createdAt: 'asc' },
+      take: this.batchSize,
+    });
+
+    if (events.length === 0) return;
+
+    for (const event of events) {
+      try {
+        // Publish to Kafka with event ID as key for deduplication
+        await this.producer.send({
+          topic: event.eventType,
+          messages: [
+            {
+              key: event.aggregateId,
+              value: JSON.stringify(event.payload),
+              headers: { 'outbox-id': event.id },
+            },
+          ],
+        });
+
+        // Mark as published
+        await this.db.outbox.update({
+          where: { id: event.id },
+          data: { publishedAt: new Date() },
+        });
+      } catch (err) {
+        await this.db.outbox.update({
+          where: { id: event.id },
+          data: {
+            publishAttempts: { increment: 1 },
+            error: (err as Error).message,
+          },
+        });
+      }
+    }
+  }
+}
+```
+
+**CDC alternative (Debezium):** Instead of polling, use Change Data Capture to stream the outbox table changes directly to Kafka. No polling process needed — lower latency, zero overhead on DB.
+
+```yaml
+# Debezium connector config (Kafka Connect)
+connector.class: io.debezium.connector.postgresql.PostgresConnector
+database.hostname: postgres
+database.dbname: myapp
+table.include.list: public.outbox
+transforms: outbox
+transforms.outbox.type: io.debezium.transforms.outbox.EventRouter
+```
+
+## Details
+
+**Polling interval vs. latency trade-off:** Polling every 100ms gives ~100ms event latency. Polling every 5s gives 5s latency. CDC gives near-zero latency but adds infrastructure complexity.
+
+**Exactly-once delivery:** The outbox gives at-least-once. To achieve exactly-once, consumers must deduplicate using the outbox record ID (stored in message headers). See `events-idempotency` skill.
+
+**Anti-patterns:**
+
+- Publishing inside the application after the transaction (dual-write) — defeats the purpose
+- Outbox table that grows unboundedly — prune published events after a retention period
+- Missing index on `WHERE published_at IS NULL` — polling becomes a full table scan under load
+
+**Retention cleanup:**
+
+```sql
+DELETE FROM outbox
+WHERE published_at IS NOT NULL
+  AND published_at < NOW() - INTERVAL '7 days';
+```
+
+## Source
+
+microservices.io/patterns/data/transactional-outbox.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/events-outbox-pattern/skill.yaml

@@ -0,0 +1,43 @@
+name: events-outbox-pattern
+version: "1.0.0"
+description: Reliably publish domain events using the transactional outbox and CDC polling approach
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/events/**"
+  - "**/queues/**"
+  - "**/handlers/**"
+  - "**/socket/**"
+  - "**/pub-sub/**"
+related_skills:
+  - microservices-outbox-pattern
+  - events-idempotency
+  - events-kafka-patterns
+stack_signals:
+  - nodejs
+  - typescript
+  - kafka
+  - redis
+  - rabbitmq
+keywords:
+  - outbox
+  - transactional-outbox
+  - CDC
+  - polling-publisher
+  - reliable-delivery
+metadata:
+  author: community
+  upstream: microservices.io/patterns/data/transactional-outbox.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/events-pubsub-pattern/SKILL.md

@@ -0,0 +1,158 @@
+# Events: Pub/Sub Pattern
+
+> Implement publisher-subscriber communication with topic-based routing and fan-out delivery.
+
+## When to Use
+
+- You need to broadcast events to multiple independent subscribers
+- Publishers and subscribers should be decoupled — publishers don't know who's listening
+- You want fan-out delivery (one event → many handlers)
+- You're implementing domain events, integration events, or notification fan-out
+- NOT when you need guaranteed exactly-once delivery (use a message queue instead)
+
+## Instructions
+
+**In-process typed pub/sub:**
+
+```typescript
+type Listener<T> = (payload: T) => void | Promise<void>;
+
+class PubSub {
+  private topics = new Map<string, Set<Listener<unknown>>>();
+
+  subscribe<T>(topic: string, listener: Listener<T>): () => void {
+    if (!this.topics.has(topic)) this.topics.set(topic, new Set());
+    this.topics.get(topic)!.add(listener as Listener<unknown>);
+    return () => this.topics.get(topic)?.delete(listener as Listener<unknown>);
+  }
+
+  async publish<T>(topic: string, payload: T): Promise<void> {
+    const listeners = this.topics.get(topic) ?? new Set();
+    await Promise.all([...listeners].map((l) => l(payload)));
+  }
+}
+
+// Define topics with types
+interface AppTopics {
+  'user.created': { userId: string; email: string; createdAt: Date };
+  'order.placed': { orderId: string; userId: string; total: number };
+  'payment.processed': { orderId: string; status: 'success' | 'failed' };
+}
+
+// Type-safe wrapper
+class TypedPubSub<Topics extends Record<string, unknown>> {
+  private bus = new PubSub();
+
+  subscribe<K extends keyof Topics & string>(topic: K, listener: Listener<Topics[K]>): () => void {
+    return this.bus.subscribe(topic, listener);
+  }
+
+  async publish<K extends keyof Topics & string>(topic: K, payload: Topics[K]): Promise<void> {
+    await this.bus.publish(topic, payload);
+  }
+}
+
+const pubsub = new TypedPubSub<AppTopics>();
+
+// Subscribers register independently
+pubsub.subscribe('user.created', async ({ userId, email }) => {
+  await sendWelcomeEmail(email);
+});
+
+pubsub.subscribe('user.created', async ({ userId }) => {
+  await createDefaultProfile(userId);
+});
+
+pubsub.subscribe('order.placed', async ({ orderId, total }) => {
+  await reserveInventory(orderId);
+  await chargeTax(total);
+});
+
+// Publisher doesn't know about subscribers
+await pubsub.publish('user.created', {
+  userId: 'u-123',
+  email: 'alice@example.com',
+  createdAt: new Date(),
+});
+```
+
+**Topic wildcards and pattern matching:**
+
+```typescript
+class WildcardPubSub {
+  private subscriptions: { pattern: RegExp; listener: Listener<unknown> }[] = [];
+
+  subscribe<T>(pattern: string, listener: Listener<T>): () => void {
+    // Convert glob to regex: 'order.*' → /^order\..+$/
+    const regex = new RegExp('^' + pattern.replace(/\./g, '\\.').replace(/\*/g, '.+') + '$');
+    const entry = { pattern: regex, listener: listener as Listener<unknown> };
+    this.subscriptions.push(entry);
+    return () => {
+      this.subscriptions = this.subscriptions.filter((s) => s !== entry);
+    };
+  }
+
+  async publish<T>(topic: string, payload: T): Promise<void> {
+    const matching = this.subscriptions.filter((s) => s.pattern.test(topic));
+    await Promise.all(matching.map((s) => s.listener(payload)));
+  }
+}
+
+const bus = new WildcardPubSub();
+bus.subscribe('order.*', (payload) => console.log('Any order event:', payload));
+bus.subscribe('*.created', (payload) => console.log('Any created event:', payload));
+await bus.publish('order.created', { orderId: '123' }); // matches both
+```
+
+## Details
+
+**Pub/Sub vs. Message Queue:**
+| | Pub/Sub | Message Queue |
+|---|---|---|
+| Delivery | At-most-once (fire & forget) | At-least-once (persisted) |
+| Consumers | Many (fan-out) | Competing (one wins) |
+| History | No replay | Replay/DLQ |
+| Use case | Real-time notifications | Reliable task processing |
+
+Use pub/sub for notifications and fan-out. Use a queue when you need guaranteed processing.
+
+**At-most-once delivery:** If a subscriber crashes or throws, the event is lost. For critical events (payments, order state changes), use a message queue or transactional outbox instead.
+
+**Anti-patterns:**
+
+- Publishing synchronously inside a transaction — if the transaction rolls back, the event has already been sent
+- Subscribers that throw exceptions without handling them — one bad subscriber can block all others; wrap each listener in try/catch
+- Circular pub/sub chains — event A triggers event B which triggers event A
+
+**Error isolation:**
+
+```typescript
+async publish<T>(topic: string, payload: T): Promise<void> {
+  const listeners = this.topics.get(topic) ?? new Set();
+  const results = await Promise.allSettled([...listeners].map(l => l(payload)));
+  const failures = results.filter(r => r.status === 'rejected');
+  if (failures.length > 0) {
+    console.error(`${failures.length} subscriber(s) failed for topic: ${topic}`);
+  }
+}
+```
+
+## Source
+
+microservices.io/patterns/data/event-sourcing.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/events-pubsub-pattern/skill.yaml

@@ -0,0 +1,44 @@
+name: events-pubsub-pattern
+version: "1.0.0"
+description: Implement publisher-subscriber communication with topic-based routing and fan-out delivery
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/events/**"
+  - "**/queues/**"
+  - "**/handlers/**"
+  - "**/socket/**"
+  - "**/pub-sub/**"
+related_skills:
+  - node-event-emitter
+  - gof-observer-pattern
+  - events-message-queue
+stack_signals:
+  - nodejs
+  - typescript
+  - kafka
+  - redis
+  - rabbitmq
+keywords:
+  - pubsub
+  - publisher
+  - subscriber
+  - topic-based
+  - fan-out
+  - at-most-once
+metadata:
+  author: community
+  upstream: microservices.io/patterns/data/event-sourcing.html
+state:
+  persistent: false
+  files: []
+depends_on: []