@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-realtime/SKILL.md

@@ -0,0 +1,733 @@
+# Skill: Configure Realtime
+
+Add realtime features to a MARS application using SSE, Pusher, or Ably, with a provider abstraction so the transport can be swapped without rewriting feature code.
+
+## When to Use
+
+Use this skill when the user asks to add realtime updates, live notifications, websockets, SSE, Pusher, Ably, live collaboration, chat, or activity feeds (e.g., "add live updates", "add realtime notifications", "set up Pusher").
+
+## Prerequisites
+
+- Read `src/config/app.config.ts` to check current service configuration.
+- Decide on a provider: **SSE** (zero dependencies, serverless-limited), **Pusher** (managed, scales well), or **Ably** (managed, richer SDK).
+
+## Architecture Overview
+
+```
+app.config.ts  (services.realtime.provider: 'sse' | 'pusher' | 'ably')
+       ↓
+Provider Abstraction  (src/features/realtime/server/index.ts)
+       ↓
+┌──────────┬──────────┬──────────┐
+│   SSE    │  Pusher  │   Ably   │
+└──────────┴──────────┴──────────┘
+       ↓
+Client Hooks  (src/features/realtime/hooks/)
+```
+
+## Step 1: Feature Structure
+
+```
+src/features/realtime/
+├── server/
+│   ├── index.ts          # Provider abstraction + factory
+│   ├── sse.ts            # SSE provider implementation
+│   ├── pusher.ts         # Pusher provider implementation
+│   └── ably.ts           # Ably provider implementation
+├── hooks/
+│   ├── index.ts          # Barrel export
+│   ├── use-event-source.ts   # SSE client hook
+│   ├── use-pusher.ts         # Pusher client hooks
+│   └── use-ably.ts           # Ably client hooks
+├── types.ts              # Shared types
+└── validation/
+    └── schemas.ts
+```
+
+## Step 2: Types
+
+Create `src/features/realtime/types.ts`:
+
+```typescript
+export interface RealtimeProvider {
+  publish(channel: string, event: string, data: unknown): Promise<void>;
+  authorizChannel?(socketId: string, channel: string, userId: string): Promise<unknown>;
+}
+
+export interface RealtimeEvent<T = unknown> {
+  channel: string;
+  event: string;
+  data: T;
+  timestamp: number;
+}
+
+export type RealtimeProviderType = 'sse' | 'pusher' | 'ably';
+```
+
+## Step 3: Provider Abstraction
+
+Create `src/features/realtime/server/index.ts`:
+
+```typescript
+import 'server-only';
+
+import { appConfig } from '@/config/app.config';
+import type { RealtimeProvider } from '../types';
+
+let _provider: RealtimeProvider | null = null;
+
+export async function getRealtimeProvider(): Promise<RealtimeProvider> {
+  if (_provider) return _provider;
+
+  const providerType = appConfig.services?.realtime?.provider ?? 'sse';
+
+  switch (providerType) {
+    case 'pusher': {
+      const { PusherProvider } = await import('./pusher');
+      _provider = new PusherProvider();
+      break;
+    }
+    case 'ably': {
+      const { AblyProvider } = await import('./ably');
+      _provider = new AblyProvider();
+      break;
+    }
+    case 'sse':
+    default: {
+      const { SSEProvider } = await import('./sse');
+      _provider = new SSEProvider();
+      break;
+    }
+  }
+
+  return _provider;
+}
+
+export async function publish(channel: string, event: string, data: unknown) {
+  const provider = await getRealtimeProvider();
+  return provider.publish(channel, event, data);
+}
+```
+
+## Step 4: SSE Provider
+
+### Server — `src/features/realtime/server/sse.ts`
+
+```typescript
+import 'server-only';
+
+import type { RealtimeProvider, RealtimeEvent } from '../types';
+
+type Subscriber = (event: RealtimeEvent) => void;
+
+const subscribers = new Map<string, Set<Subscriber>>();
+
+export class SSEProvider implements RealtimeProvider {
+  async publish(channel: string, event: string, data: unknown): Promise<void> {
+    const channelSubs = subscribers.get(channel);
+    if (!channelSubs) return;
+
+    const realtimeEvent: RealtimeEvent = {
+      channel,
+      event,
+      data,
+      timestamp: Date.now(),
+    };
+
+    for (const subscriber of channelSubs) {
+      subscriber(realtimeEvent);
+    }
+  }
+}
+
+export function subscribe(channel: string, callback: Subscriber): () => void {
+  if (!subscribers.has(channel)) {
+    subscribers.set(channel, new Set());
+  }
+  subscribers.get(channel)!.add(callback);
+
+  return () => {
+    subscribers.get(channel)?.delete(callback);
+    if (subscribers.get(channel)?.size === 0) {
+      subscribers.delete(channel);
+    }
+  };
+}
+```
+
+### SSE API Route — `src/app/api/protected/realtime/stream/route.ts`
+
+```typescript
+import { verifySessionForAPI } from '@/lib/mars';
+import { subscribe } from '@/features/realtime/server/sse';
+import { NextRequest } from 'next/server';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: NextRequest) {
+  const session = await verifySessionForAPI(request);
+  if (!session) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  const channel = request.nextUrl.searchParams.get('channel');
+  if (!channel) {
+    return new Response('Channel parameter required', { status: 400 });
+  }
+
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(': connected\n\n'));
+
+      const unsubscribe = subscribe(channel, (event) => {
+        const payload = `event: ${event.event}\ndata: ${JSON.stringify(event.data)}\n\n`;
+        controller.enqueue(encoder.encode(payload));
+      });
+
+      request.signal.addEventListener('abort', () => {
+        unsubscribe();
+        controller.close();
+      });
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'Transfer-Encoding': 'chunked',
+    },
+  });
+}
+```
+
+**Serverless caveat:** SSE connections time out on serverless platforms (max ~30s on Vercel). The client hook must handle reconnection. For production use with many concurrent users, prefer Pusher or Ably.
+
+### SSE Client Hook — `src/features/realtime/hooks/use-event-source.ts`
+
+```typescript
+'use client';
+
+import { useEffect, useRef, useCallback, useState } from 'react';
+
+interface UseEventSourceOptions {
+  channel: string;
+  events: string[];
+  onEvent: (event: string, data: unknown) => void;
+  enabled?: boolean;
+}
+
+export function useEventSource({ channel, events, onEvent, enabled = true }: UseEventSourceOptions) {
+  const [connected, setConnected] = useState(false);
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const retriesRef = useRef(0);
+
+  const connect = useCallback(() => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+    }
+
+    const url = `/api/protected/realtime/stream?channel=${encodeURIComponent(channel)}`;
+    const es = new EventSource(url, { withCredentials: true });
+
+    es.onopen = () => {
+      setConnected(true);
+      retriesRef.current = 0;
+    };
+
+    for (const eventName of events) {
+      es.addEventListener(eventName, (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data);
+          onEvent(eventName, data);
+        } catch {
+          onEvent(eventName, e.data);
+        }
+      });
+    }
+
+    es.onerror = () => {
+      setConnected(false);
+      es.close();
+
+      const delay = Math.min(1000 * 2 ** retriesRef.current, 30000);
+      retriesRef.current += 1;
+
+      reconnectTimeoutRef.current = setTimeout(connect, delay);
+    };
+
+    eventSourceRef.current = es;
+  }, [channel, events, onEvent]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    connect();
+
+    return () => {
+      eventSourceRef.current?.close();
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+    };
+  }, [connect, enabled]);
+
+  return { connected };
+}
+```
+
+## Step 5: Pusher Provider
+
+### Install
+
+```bash
+yarn add pusher pusher-js
+```
+
+### Environment Variables
+
+```bash
+PUSHER_APP_ID="your_app_id"
+PUSHER_KEY="your_key"
+PUSHER_SECRET="your_secret"
+PUSHER_CLUSTER="us2"
+NEXT_PUBLIC_PUSHER_KEY="your_key"
+NEXT_PUBLIC_PUSHER_CLUSTER="us2"
+```
+
+### Server — `src/features/realtime/server/pusher.ts`
+
+```typescript
+import 'server-only';
+
+import Pusher from 'pusher';
+import type { RealtimeProvider } from '../types';
+
+let _pusher: Pusher | null = null;
+
+function getPusher(): Pusher {
+  if (_pusher) return _pusher;
+
+  const appId = process.env.PUSHER_APP_ID;
+  const key = process.env.PUSHER_KEY;
+  const secret = process.env.PUSHER_SECRET;
+  const cluster = process.env.PUSHER_CLUSTER;
+
+  if (!appId || !key || !secret || !cluster) {
+    throw new Error(
+      'Pusher credentials not set.\n'
+      + '  → Set PUSHER_APP_ID, PUSHER_KEY, PUSHER_SECRET, PUSHER_CLUSTER in .env\n'
+      + '  → Get credentials from https://dashboard.pusher.com',
+    );
+  }
+
+  _pusher = new Pusher({ appId, key, secret, cluster, useTLS: true });
+  return _pusher;
+}
+
+export class PusherProvider implements RealtimeProvider {
+  async publish(channel: string, event: string, data: unknown): Promise<void> {
+    await getPusher().trigger(channel, event, data);
+  }
+
+  async authorizChannel(socketId: string, channel: string, userId: string) {
+    const pusher = getPusher();
+
+    if (channel.startsWith('private-')) {
+      return pusher.authorizeChannel(socketId, channel);
+    }
+
+    if (channel.startsWith('presence-')) {
+      return pusher.authorizeChannel(socketId, channel, {
+        user_id: userId,
+      });
+    }
+
+    throw new Error(`Cannot authorize public channel: ${channel}`);
+  }
+}
+```
+
+### Pusher Auth Route — `src/app/api/protected/realtime/pusher-auth/route.ts`
+
+```typescript
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { PusherProvider } from '@/features/realtime/server/pusher';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const authSchema = z.object({
+  socket_id: z.string().min(1),
+  channel_name: z.string().min(1),
+});
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const body = authSchema.parse(await request.json());
+    const provider = new PusherProvider();
+    const auth = await provider.authorizChannel(
+      body.socket_id,
+      body.channel_name,
+      request.session.userId,
+    );
+    return NextResponse.json(auth);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/realtime/pusher-auth' });
+  }
+});
+```
+
+### Pusher Client Hooks — `src/features/realtime/hooks/use-pusher.ts`
+
+```typescript
+'use client';
+
+import { useEffect, useRef, useState, useCallback } from 'react';
+import PusherClient from 'pusher-js';
+import type { Channel } from 'pusher-js';
+
+let _pusherClient: PusherClient | null = null;
+
+function getPusherClient(): PusherClient {
+  if (_pusherClient) return _pusherClient;
+
+  _pusherClient = new PusherClient(process.env.NEXT_PUBLIC_PUSHER_KEY!, {
+    cluster: process.env.NEXT_PUBLIC_PUSHER_CLUSTER!,
+    channelAuthorization: {
+      endpoint: '/api/protected/realtime/pusher-auth',
+      transport: 'ajax',
+    },
+  });
+
+  return _pusherClient;
+}
+
+export function useChannel(channelName: string): Channel | null {
+  const [channel, setChannel] = useState<Channel | null>(null);
+
+  useEffect(() => {
+    const pusher = getPusherClient();
+    const ch = pusher.subscribe(channelName);
+    setChannel(ch);
+
+    return () => {
+      pusher.unsubscribe(channelName);
+      setChannel(null);
+    };
+  }, [channelName]);
+
+  return channel;
+}
+
+export function useEvent<T = unknown>(
+  channel: Channel | null,
+  eventName: string,
+  callback: (data: T) => void,
+) {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!channel) return;
+
+    const handler = (data: T) => callbackRef.current(data);
+    channel.bind(eventName, handler);
+
+    return () => {
+      channel.unbind(eventName, handler);
+    };
+  }, [channel, eventName]);
+}
+```
+
+## Step 6: Ably Provider
+
+### Install
+
+```bash
+yarn add ably
+```
+
+### Environment Variables
+
+```bash
+ABLY_API_KEY="your_api_key"
+NEXT_PUBLIC_ABLY_KEY="your_publishable_key"
+```
+
+### Server — `src/features/realtime/server/ably.ts`
+
+```typescript
+import 'server-only';
+
+import Ably from 'ably';
+import type { RealtimeProvider } from '../types';
+
+let _ably: Ably.Rest | null = null;
+
+function getAbly(): Ably.Rest {
+  if (_ably) return _ably;
+
+  const apiKey = process.env.ABLY_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      'ABLY_API_KEY is not set.\n'
+      + '  → Get your key from https://ably.com/accounts\n'
+      + '  → Add it to your .env file',
+    );
+  }
+
+  _ably = new Ably.Rest({ key: apiKey });
+  return _ably;
+}
+
+export class AblyProvider implements RealtimeProvider {
+  async publish(channel: string, event: string, data: unknown): Promise<void> {
+    const ably = getAbly();
+    const ch = ably.channels.get(channel);
+    await ch.publish(event, data);
+  }
+
+  async authorizChannel(_socketId: string, _channel: string, userId: string) {
+    const ably = getAbly();
+    return ably.auth.createTokenRequest({ clientId: userId });
+  }
+}
+```
+
+### Ably Token Auth Route — `src/app/api/protected/realtime/ably-auth/route.ts`
+
+```typescript
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { AblyProvider } from '@/features/realtime/server/ably';
+import { NextResponse } from 'next/server';
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const provider = new AblyProvider();
+    const tokenRequest = await provider.authorizChannel('', '', request.session.userId);
+    return NextResponse.json(tokenRequest);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/realtime/ably-auth' });
+  }
+});
+```
+
+### Ably Client Hooks — `src/features/realtime/hooks/use-ably.ts`
+
+```typescript
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import * as Ably from 'ably';
+import type { RealtimeChannel } from 'ably';
+
+let _ablyClient: Ably.Realtime | null = null;
+
+function getAblyClient(): Ably.Realtime {
+  if (_ablyClient) return _ablyClient;
+
+  _ablyClient = new Ably.Realtime({
+    authUrl: '/api/protected/realtime/ably-auth',
+    authMethod: 'POST',
+  });
+
+  return _ablyClient;
+}
+
+export function useAblyChannel(channelName: string): RealtimeChannel | null {
+  const [channel, setChannel] = useState<RealtimeChannel | null>(null);
+
+  useEffect(() => {
+    const ably = getAblyClient();
+    const ch = ably.channels.get(channelName);
+    setChannel(ch);
+
+    return () => {
+      ch.detach();
+      setChannel(null);
+    };
+  }, [channelName]);
+
+  return channel;
+}
+
+export function useAblyEvent<T = unknown>(
+  channel: RealtimeChannel | null,
+  eventName: string,
+  callback: (data: T) => void,
+) {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!channel) return;
+
+    const handler = (message: Ably.Message) => {
+      callbackRef.current(message.data as T);
+    };
+
+    channel.subscribe(eventName, handler);
+
+    return () => {
+      channel.unsubscribe(eventName, handler);
+    };
+  }, [channel, eventName]);
+}
+```
+
+## Step 7: Service Config Integration
+
+Add to `src/config/app.config.ts`:
+
+```typescript
+services: {
+  // ... existing services
+  realtime: {
+    provider: 'pusher', // 'sse' | 'pusher' | 'ably'
+  },
+},
+
+features: {
+  // ... existing flags
+  realtime: true,
+}
+```
+
+## Step 8: Common Patterns
+
+### Notification Feed
+
+```typescript
+// Server: publish when something happens
+import { publish } from '@/features/realtime/server';
+
+await publish(`user-${userId}`, 'notification', {
+  title: 'New comment',
+  body: 'Someone commented on your post',
+  url: '/posts/123',
+});
+
+// Client: listen for notifications
+import { useChannel, useEvent } from '@/features/realtime/hooks/use-pusher';
+
+function NotificationBell({ userId }: { userId: string }) {
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+  const channel = useChannel(`private-user-${userId}`);
+
+  useEvent(channel, 'notification', (data: Notification) => {
+    setNotifications((prev) => [data, ...prev]);
+  });
+
+  return <NotificationList items={notifications} />;
+}
+```
+
+### Live Collaboration Cursors
+
+```typescript
+// Broadcast cursor position
+import { publish } from '@/features/realtime/server';
+
+await publish(`document-${docId}`, 'cursor-move', {
+  userId,
+  x: cursor.x,
+  y: cursor.y,
+  color: userColor,
+});
+```
+
+### Chat Messages
+
+```typescript
+// Server: broadcast new message
+await publish(`chat-${roomId}`, 'message', {
+  id: message.id,
+  userId: message.userId,
+  text: message.text,
+  createdAt: message.createdAt,
+});
+```
+
+### Activity Stream
+
+```typescript
+// Server: publish activity events
+await publish(`org-${orgId}`, 'activity', {
+  actor: { id: userId, name: userName },
+  action: 'created',
+  target: { type: 'document', id: docId, name: docName },
+  timestamp: Date.now(),
+});
+```
+
+## Provider Comparison
+
+| Feature | SSE | Pusher | Ably |
+|---------|-----|--------|------|
+| Dependencies | None | `pusher`, `pusher-js` | `ably` |
+| Serverless-friendly | Limited (30s timeout) | Yes | Yes |
+| Private channels | Manual auth | Built-in | Built-in |
+| Presence | Manual | Built-in | Built-in |
+| Max connections | Process-bound | 100+ concurrent (free) | 200+ concurrent (free) |
+| Cost | Free | Free tier, then paid | Free tier, then paid |
+| Complexity | Low | Medium | Medium |
+
+**Recommendation:** Use SSE for prototyping or low-traffic internal tools. Use Pusher for most production apps (best DX). Use Ably if you need advanced features like message history or guaranteed ordering.
+
+## Tests
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { SSEProvider } from './sse';
+
+describe('SSEProvider', () => {
+  it('publishes events to subscribers', async () => {
+    const provider = new SSEProvider();
+    const callback = vi.fn();
+
+    const { subscribe } = await import('./sse');
+    const unsubscribe = subscribe('test-channel', callback);
+
+    await provider.publish('test-channel', 'test-event', { hello: 'world' });
+
+    expect(callback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: 'test-channel',
+        event: 'test-event',
+        data: { hello: 'world' },
+      }),
+    );
+
+    unsubscribe();
+  });
+});
+```
+
+Mock the provider for feature tests:
+
+```typescript
+vi.mock('@/features/realtime/server', () => ({
+  publish: vi.fn(),
+  getRealtimeProvider: vi.fn(() => ({
+    publish: vi.fn(),
+  })),
+}));
+```
+
+## Checklist
+
+- [ ] Feature structure created (`src/features/realtime/`)
+- [ ] Provider type added to `types.ts`
+- [ ] Provider abstraction with factory in `server/index.ts`
+- [ ] SSE provider implemented with stream route and client hook
+- [ ] Pusher provider implemented with auth route and client hooks (if using Pusher)
+- [ ] Ably provider implemented with token route and client hooks (if using Ably)
+- [ ] Environment variables documented and added to `.env`
+- [ ] `app.config.ts` updated with `services.realtime` and `features.realtime`
+- [ ] Client hooks handle reconnection and cleanup
+- [ ] Auth enforced on all realtime endpoints
+- [ ] Tests written for provider abstraction and SSE provider
+- [ ] Serverless timeout caveat documented for SSE