@harness-engineering/cli 1.23.2 → 1.24.0

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

@@ -0,0 +1,183 @@
+# Events: Redis Pub/Sub
+
+> Use Redis pub/sub channels and keyspace notifications for lightweight real-time messaging.
+
+## When to Use
+
+- You need low-latency, real-time messaging within a trusted system (not across the internet)
+- You want to fan-out cache invalidation signals across service instances
+- You're building a simple real-time feature (live counters, notifications, presence) and don't need persistence
+- You need keyspace notifications (react when a Redis key changes, expires, or is deleted)
+- NOT when you need guaranteed delivery or message persistence — Redis pub/sub is fire-and-forget
+
+## Instructions
+
+**Basic pub/sub with ioredis:**
+
+```typescript
+import Redis from 'ioredis';
+
+const publisher = new Redis({ host: 'localhost', port: 6379 });
+const subscriber = new Redis({ host: 'localhost', port: 6379 });
+// Note: subscriber connection CANNOT be used for other commands
+
+// Subscribe to channels
+await subscriber.subscribe('cache.invalidation', 'user.presence');
+
+subscriber.on('message', (channel: string, message: string) => {
+  console.log(`[${channel}] ${message}`);
+
+  if (channel === 'cache.invalidation') {
+    const { key } = JSON.parse(message);
+    localCache.delete(key);
+  }
+
+  if (channel === 'user.presence') {
+    const { userId, status } = JSON.parse(message);
+    updatePresence(userId, status);
+  }
+});
+
+// Publish from anywhere (different connection)
+async function invalidateCache(key: string): Promise<void> {
+  await publisher.publish('cache.invalidation', JSON.stringify({ key, timestamp: Date.now() }));
+}
+
+async function updateUserPresence(userId: string, status: 'online' | 'offline'): Promise<void> {
+  await publisher.publish('user.presence', JSON.stringify({ userId, status }));
+}
+```
+
+**Pattern subscriptions (wildcard channels):**
+
+```typescript
+// Subscribe to all channels matching a pattern
+await subscriber.psubscribe('order.*');
+
+subscriber.on('pmessage', (pattern: string, channel: string, message: string) => {
+  console.log(`Pattern: ${pattern}, Channel: ${channel}, Message: ${message}`);
+  // pattern = 'order.*', channel = 'order.created', message = '{"orderId":"..."}'
+
+  const eventType = channel.split('.')[1]; // 'created', 'shipped', etc.
+  handleOrderEvent(eventType, JSON.parse(message));
+});
+
+// Publish to specific channels — matched by pattern
+await publisher.publish('order.created', JSON.stringify({ orderId: '123' }));
+await publisher.publish('order.shipped', JSON.stringify({ orderId: '123', tracking: 'UPS123' }));
+```
+
+**Keyspace notifications (react to Redis key events):**
+
+```typescript
+// Enable keyspace notifications in Redis config (or via command)
+// notify-keyspace-events "Ex" — expired events
+// notify-keyspace-events "KEx" — keyspace + expired events
+
+const adminClient = new Redis({ host: 'localhost', port: 6379 });
+await adminClient.config('SET', 'notify-keyspace-events', 'Ex'); // enable expired events
+
+const notifSub = new Redis({ host: 'localhost', port: 6379 });
+await notifSub.psubscribe('__keyevent@0__:expired'); // channel for db 0 key expirations
+
+notifSub.on('pmessage', (_pattern, _channel, key) => {
+  console.log(`Key expired: ${key}`);
+  // e.g., session expired → log out user
+  if (key.startsWith('session:')) {
+    const userId = key.replace('session:', '');
+    handleSessionExpiry(userId);
+  }
+});
+
+// Set a key with expiry — triggers the notification when it expires
+await adminClient.set('session:user-123', 'active', 'EX', 3600);
+```
+
+**Typed channel wrapper:**
+
+```typescript
+type Channels = {
+  'cache.invalidation': { key: string; timestamp: number };
+  'user.presence': { userId: string; status: 'online' | 'offline' };
+};
+
+class TypedRedisChannel<C extends Record<string, unknown>> {
+  constructor(
+    private readonly pub: Redis,
+    private readonly sub: Redis
+  ) {}
+
+  async publish<K extends keyof C & string>(channel: K, data: C[K]): Promise<void> {
+    await this.pub.publish(channel, JSON.stringify(data));
+  }
+
+  subscribe<K extends keyof C & string>(channel: K, handler: (data: C[K]) => void): () => void {
+    this.sub.subscribe(channel);
+    const listener = (ch: string, msg: string) => {
+      if (ch === channel) handler(JSON.parse(msg) as C[K]);
+    };
+    this.sub.on('message', listener);
+    return () => {
+      this.sub.unsubscribe(channel);
+      this.sub.off('message', listener);
+    };
+  }
+}
+
+const channels = new TypedRedisChannel<Channels>(publisher, subscriber);
+channels.subscribe('cache.invalidation', ({ key }) => localCache.delete(key));
+await channels.publish('cache.invalidation', { key: 'user:123', timestamp: Date.now() });
+```
+
+## Details
+
+**Redis pub/sub is at-most-once:** If a subscriber is down when a message is published, the message is lost. For critical notifications, use a message queue or Redis Streams instead.
+
+**Redis Streams vs. pub/sub:**
+| Feature | Pub/Sub | Streams |
+|---|---|---|
+| Persistence | No | Yes |
+| Consumer groups | No | Yes |
+| Message history | No | Yes (by ID) |
+| Delivery | At-most-once | At-least-once |
+
+Use Streams when you need durability. Use pub/sub for lightweight real-time signals.
+
+**Anti-patterns:**
+
+- Using pub/sub for work queues — use BullMQ or a queue library instead
+- Sharing the subscriber connection for regular Redis commands — subscribed connections are dedicated
+- Not handling subscriber reconnection — ioredis auto-reconnects but you must re-subscribe in the `connect` event
+
+**Reconnection handling:**
+
+```typescript
+subscriber.on('reconnecting', () => {
+  console.log('Reconnecting to Redis...');
+});
+
+subscriber.on('ready', async () => {
+  // Re-subscribe after reconnect
+  await subscriber.subscribe('cache.invalidation', 'user.presence');
+});
+```
+
+## Source
+
+redis.io/docs/latest/develop/interact/pubsub/
+
+## 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-redis-pubsub/skill.yaml

@@ -0,0 +1,42 @@
+name: events-redis-pubsub
+version: "1.0.0"
+description: Use Redis pub/sub channels and keyspace notifications for lightweight real-time messaging
+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-message-queue
+stack_signals:
+  - nodejs
+  - typescript
+  - kafka
+  - redis
+  - rabbitmq
+keywords:
+  - redis
+  - pubsub
+  - channels
+  - pattern-subscriptions
+  - keyspace-notifications
+metadata:
+  author: community
+  upstream: redis.io/docs/latest/develop/interact/pubsub/
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/events-saga-choreography/SKILL.md

@@ -0,0 +1,177 @@
+# Events: Saga Choreography
+
+> Coordinate distributed workflows through event chains and compensation events without an orchestrator.
+
+## When to Use
+
+- You have a multi-step business transaction spanning multiple services
+- You want loose coupling — services react to events without a central coordinator
+- You need to roll back partial work using compensation events when a step fails
+- Your workflow is relatively linear (A → B → C → done) with clear compensation paths
+- Prefer choreography over orchestration for simpler flows; use orchestration for complex branching
+
+## Instructions
+
+**Order fulfillment saga (choreography):**
+
+```
+ORDER CREATED
+    → Payment Service: charge card
+        → PAYMENT_PROCESSED
+            → Inventory Service: reserve stock
+                → INVENTORY_RESERVED
+                    → Shipping Service: create shipment
+                        → SHIPMENT_CREATED → done
+
+On failure at any step → emit compensation event → previous steps compensate:
+PAYMENT_FAILED → saga ends (nothing to compensate)
+INVENTORY_FAILED → emit PAYMENT_REFUND_REQUESTED → Payment Service refunds
+SHIPPING_FAILED → emit INVENTORY_RELEASE_REQUESTED + PAYMENT_REFUND_REQUESTED
+```
+
+**Order service — publishes the saga trigger:**
+
+```typescript
+// 1. Create order and publish triggering event
+async function createOrder(data: CreateOrderInput): Promise<Order> {
+  return prisma.$transaction(async (tx) => {
+    const order = await tx.order.create({
+      data: { ...data, status: 'AWAITING_PAYMENT' },
+    });
+
+    await tx.outbox.create({
+      data: {
+        eventType: 'order.created',
+        aggregateId: order.id,
+        payload: {
+          eventId: crypto.randomUUID(),
+          orderId: order.id,
+          userId: order.userId,
+          amount: order.total,
+          items: order.items,
+        },
+      },
+    });
+
+    return order;
+  });
+}
+
+// Listen for saga completion/failure events
+consumer.on('order.saga.completed', async ({ orderId }) => {
+  await db.order.update({ where: { id: orderId }, data: { status: 'CONFIRMED' } });
+});
+
+consumer.on('order.saga.failed', async ({ orderId, reason }) => {
+  await db.order.update({
+    where: { id: orderId },
+    data: { status: 'FAILED', failureReason: reason },
+  });
+});
+```
+
+**Payment service — listens and reacts:**
+
+```typescript
+consumer.on('order.created', async (event) => {
+  const { orderId, userId, amount } = event;
+
+  try {
+    const charge = await stripe.charges.create({
+      amount: Math.round(amount * 100),
+      currency: 'usd',
+      customer: await getStripeCustomerId(userId),
+    });
+
+    // Success → publish next saga event
+    await publish('payment.processed', {
+      eventId: crypto.randomUUID(),
+      orderId,
+      chargeId: charge.id,
+      amount,
+    });
+  } catch (err) {
+    // Failure → publish compensation event
+    await publish('payment.failed', {
+      eventId: crypto.randomUUID(),
+      orderId,
+      reason: (err as Error).message,
+    });
+  }
+});
+
+// Compensation — triggered by downstream failure
+consumer.on('payment.refund.requested', async ({ orderId, chargeId }) => {
+  await stripe.refunds.create({ charge: chargeId });
+  await publish('payment.refunded', { eventId: crypto.randomUUID(), orderId, chargeId });
+});
+```
+
+**Inventory service:**
+
+```typescript
+consumer.on('payment.processed', async ({ orderId, chargeId, items }) => {
+  try {
+    await reserveInventory(items);
+    await publish('inventory.reserved', { eventId: crypto.randomUUID(), orderId, chargeId });
+  } catch (err) {
+    // Cannot reserve → trigger payment compensation
+    await publish('inventory.reservation.failed', {
+      eventId: crypto.randomUUID(),
+      orderId,
+      chargeId,
+      reason: (err as Error).message,
+    });
+    // Payment service listens to this and refunds
+  }
+});
+
+consumer.on('inventory.release.requested', async ({ orderId, items }) => {
+  await releaseInventory(items);
+  await publish('inventory.released', { eventId: crypto.randomUUID(), orderId });
+});
+```
+
+## Details
+
+**Choreography vs. Orchestration:**
+| | Choreography | Orchestration |
+|---|---|---|
+| Control | Distributed (each service reacts) | Centralized (saga orchestrator commands) |
+| Coupling | Low — services share events | Higher — orchestrator knows all steps |
+| Visibility | Hard — no single view of progress | Easy — orchestrator tracks state |
+| Complexity | Simple flows | Complex flows, conditional branches |
+
+**Idempotency is mandatory:** Each saga step must be idempotent — events can be redelivered. Use event IDs and the `processed_events` table (see `events-idempotency` skill).
+
+**Anti-patterns:**
+
+- Saga steps that have side effects before the event is committed — use outbox pattern for publishing
+- Missing compensation events — if any step doesn't define a compensation, rollback becomes impossible
+- Circular compensation chains — A compensates B, B compensates A → infinite loop
+
+**Observability challenge:** With pure choreography, no single place shows the full saga state. Solutions:
+
+1. Correlation IDs on all events (same `sagaId` across all events)
+2. A saga tracker service that listens to all events and builds a state view
+3. Structured logging with the `sagaId` field for log aggregation queries
+
+## Source
+
+microservices.io/patterns/data/saga.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-saga-choreography/skill.yaml

@@ -0,0 +1,43 @@
+name: events-saga-choreography
+version: "1.0.0"
+description: Coordinate distributed workflows through event chains and compensation events without an orchestrator
+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-saga-pattern
+  - events-pubsub-pattern
+  - events-idempotency
+stack_signals:
+  - nodejs
+  - typescript
+  - kafka
+  - redis
+  - rabbitmq
+keywords:
+  - saga
+  - choreography
+  - compensation-events
+  - eventual-consistency
+  - event-chains
+metadata:
+  author: community
+  upstream: microservices.io/patterns/data/saga.html
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,221 @@
+# Events: SSE Pattern
+
+> Stream one-way server events to browsers using Server-Sent Events and EventSource.
+
+## When to Use
+
+- You need to push real-time updates from server to browser (one-way: server → client only)
+- Live notifications, activity feeds, progress indicators, live scores, stock tickers
+- You want auto-reconnect behavior built into the browser for free
+- You prefer HTTP/1.1 compatibility over WebSocket's upgrade handshake
+- NOT when the client needs to push data back to the server — use WebSocket for bidirectional communication
+
+## Instructions
+
+**Express SSE endpoint:**
+
+```typescript
+import express, { Request, Response } from 'express';
+
+const app = express();
+
+// SSE connection handler
+app.get('/events', (req: Request, res: Response) => {
+  // Required headers for SSE
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('X-Accel-Buffering', 'no'); // disable nginx buffering
+  res.flushHeaders(); // send headers immediately
+
+  // Send a comment every 30s to keep the connection alive through proxies
+  const keepAlive = setInterval(() => {
+    res.write(': keep-alive\n\n');
+  }, 30_000);
+
+  // Helper to send typed events
+  const send = (eventType: string, data: unknown, id?: string): void => {
+    if (id) res.write(`id: ${id}\n`);
+    res.write(`event: ${eventType}\n`);
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+  };
+
+  // Send initial state
+  send('connected', { timestamp: new Date().toISOString() });
+
+  // Register this client for notifications
+  const userId = req.query.userId as string;
+  const clientId = addClient(userId, send);
+
+  // Clean up when client disconnects
+  req.on('close', () => {
+    clearInterval(keepAlive);
+    removeClient(clientId);
+    console.log(`SSE client ${clientId} disconnected`);
+  });
+});
+
+// Client registry
+type SendFn = (event: string, data: unknown, id?: string) => void;
+const clients = new Map<string, { userId: string; send: SendFn }>();
+
+function addClient(userId: string, send: SendFn): string {
+  const clientId = crypto.randomUUID();
+  clients.set(clientId, { userId, send });
+  return clientId;
+}
+
+function removeClient(clientId: string): void {
+  clients.delete(clientId);
+}
+
+// Push notification to a specific user's SSE streams
+function pushToUser(userId: string, event: string, data: unknown): void {
+  for (const [, client] of clients) {
+    if (client.userId === userId) {
+      client.send(event, data, crypto.randomUUID());
+    }
+  }
+}
+
+// Broadcast to all connected clients
+function broadcast(event: string, data: unknown): void {
+  for (const [, client] of clients) {
+    client.send(event, data);
+  }
+}
+
+// Trigger from anywhere in your application
+pushToUser('user-123', 'notification', {
+  title: 'Your order shipped',
+  message: 'Order #456 is on its way',
+  timestamp: new Date().toISOString(),
+});
+```
+
+**SSE with Last-Event-ID for resumption:**
+
+```typescript
+app.get('/events/feed', async (req: Request, res: Response) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.flushHeaders();
+
+  // Resume from last seen event ID (browser sends automatically on reconnect)
+  const lastEventId = req.headers['last-event-id'] as string | undefined;
+
+  if (lastEventId) {
+    // Replay missed events
+    const missed = await db.events.findMany({
+      where: { id: { gt: lastEventId }, userId: req.user.id },
+      orderBy: { id: 'asc' },
+      take: 100,
+    });
+
+    for (const event of missed) {
+      res.write(`id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify(event.data)}\n\n`);
+    }
+  }
+
+  // Continue real-time stream...
+});
+```
+
+**Browser client:**
+
+```typescript
+// Browser — EventSource handles reconnection automatically
+const es = new EventSource('/events?userId=user-123');
+
+es.addEventListener('notification', (event: MessageEvent) => {
+  const data = JSON.parse(event.data);
+  showNotification(data.title, data.message);
+});
+
+es.addEventListener('order.updated', (event: MessageEvent) => {
+  const data = JSON.parse(event.data);
+  updateOrderStatus(data.orderId, data.status);
+});
+
+es.addEventListener('error', (event) => {
+  console.error('SSE error — browser will retry automatically');
+});
+
+// EventSource reconnects automatically on disconnect
+// It sends Last-Event-Id header to resume from where it left off
+
+// Cleanup
+function disconnect(): void {
+  es.close();
+}
+```
+
+## Details
+
+**SSE protocol format:**
+
+```
+id: <unique-event-id>\n
+event: <event-type>\n
+data: <json-string>\n
+\n                     ← blank line terminates the event
+```
+
+**Auto-reconnect:** Browser's EventSource retries after 3 seconds by default. Set custom retry interval:
+
+```
+retry: 5000\n
+\n
+```
+
+**Anti-patterns:**
+
+- Sending large payloads via SSE — SSE is for small notifications, not binary data transfers
+- Not setting `X-Accel-Buffering: no` — nginx buffers SSE responses, breaking the stream
+- No keep-alive — many proxies close idle connections after 30-60 seconds
+
+**Scaling SSE:** SSE connections are long-lived HTTP connections. Each connection holds a socket on the server. Use Redis pub/sub to distribute events across multiple server instances:
+
+```typescript
+// When running multiple Node instances
+const redisSub = new Redis(REDIS_URL);
+redisSub.subscribe('push.events');
+redisSub.on('message', (_channel, message) => {
+  const { userId, event, data } = JSON.parse(message);
+  pushToUser(userId, event, data); // push to local clients only
+});
+
+// Publisher (any service instance)
+const redisPub = new Redis(REDIS_URL);
+await redisPub.publish('push.events', JSON.stringify({ userId, event: 'notification', data }));
+```
+
+**SSE vs. WebSocket comparison:**
+| | SSE | WebSocket |
+|---|---|---|
+| Direction | Server → Client | Bidirectional |
+| Protocol | HTTP | WS upgrade |
+| Auto-reconnect | Yes (built-in) | Manual |
+| Browser support | Excellent | Excellent |
+| Proxy support | Better (HTTP) | Variable |
+
+## Source
+
+html.spec.whatwg.org/multipage/server-sent-events.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.