@terreno/mcp 58.0.0-beta.4 → 58.0.1

package/dist/docs/versioned/57.18.0/how-to/websocket-integration.md

@@ -1,474 +0,0 @@
-# How to Add WebSocket Integration
-
-Step-by-step guide to adding real-time Socket.io connections to your Terreno application using `@terreno/rtk`.
-
-## Prerequisites
-
-- Backend with Socket.io server configured
-- Frontend using `@terreno/rtk` and `@terreno/ui`
-- Redux store set up with `generateAuthSlice`
-
-## Installation
-
-Socket.io dependencies are already included in `@terreno/rtk`:
-
-``````bash
-bun install @terreno/rtk
-# socket.io-client is a peer dependency
-bun install socket.io-client
-``````
-
-## Backend Setup
-
-### 1. Add Socket.io to Express Server
-
-``````typescript
-import {createServer} from "node:http";
-import {Server} from "socket.io";
-import {setupServer} from "@terreno/api";
-
-const app = setupServer({
-  userModel: User,
-  addRoutes: (router) => {
-    // Your routes
-  },
-});
-
-const httpServer = createServer(app);
-const io = new Server(httpServer, {
-  cors: {
-    origin: process.env.FRONTEND_URL || "http://localhost:8081",
-    credentials: true,
-  },
-  transports: ["websocket"],
-});
-
-// Authentication middleware
-io.use(async (socket, next) => {
-  const token = socket.handshake.auth.token?.replace("Bearer ", "");
-  
-  if (!token) {
-    return next(new Error("Authentication required"));
-  }
-  
-  try {
-    // Verify JWT token
-    const decoded = verifyToken(token);
-    const user = await User.findById(decoded.sub);
-    
-    if (!user) {
-      return next(new Error("User not found"));
-    }
-    
-    socket.data.user = user;
-    next();
-  } catch (error) {
-    next(new Error("Invalid token"));
-  }
-});
-
-// Connection handling
-io.on("connection", (socket) => {
-  const user = socket.data.user;
-  console.log(`User connected: ${user.email} (${socket.id})`);
-  
-  // Join user-specific room
-  socket.join(`user:${user._id}`);
-  
-  // Handle custom events
-  socket.on("subscribe:todos", () => {
-    socket.join("todos");
-    console.log(`${user.email} subscribed to todos`);
-  });
-  
-  socket.on("disconnect", (reason) => {
-    console.log(`User disconnected: ${user.email} (${reason})`);
-  });
-});
-
-httpServer.listen(4000, () => {
-  console.log("Server listening on port 4000");
-});
-
-export {io}; // Export for emitting events from routes
-``````
-
-### 2. Emit Events from API Routes
-
-``````typescript
-import {io} from "./server";
-
-// In your modelRouter postCreate hook
-modelRouter(Todo, {
-  permissions: {
-    create: [Permissions.IsAuthenticated],
-  },
-  postCreate: (todo, req) => {
-    // Emit to all clients in the todos room
-    io.to("todos").emit("todo:created", {
-      id: todo._id,
-      title: todo.title,
-      ownerId: todo.ownerId,
-    });
-    
-    // Emit to specific user
-    io.to(`user:${todo.ownerId}`).emit("notification", {
-      type: "todo_created",
-      message: `Todo "${todo.title}" created`,
-    });
-  },
-});
-``````
-
-## Frontend Setup
-
-### 1. Configure WebSocket URL
-
-Add to your `app.json` or environment:
-
-``````json
-{
-  "expo": {
-    "extra": {
-      "WEBSOCKET_URL": "wss://api.example.com",
-      "WEBSOCKETS_DEBUG": false
-    }
-  }
-}
-``````
-
-### 2. Register the token source
-
-The hook reads its handshake token from the token source the app registers once at startup
-with `setTokenSource`. A JWT app registers nothing: the default source reads the JWT in
-storage. A Better Auth app registers the adapter it builds for syncdb:
-
-``````typescript
-// store/tokenSource.ts: import once from the app entry, before the store is created
-import {setTokenSource} from "@terreno/rtk";
-import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
-import {authClient} from "@/lib/betterAuth";
-
-setTokenSource(betterAuthAdapter(bridgeBetterAuthReactClient(authClient)));
-``````
-
-With `webAuth: "bearer"`, also pass the adapter `getBearerToken`
-([syncdb adapter](../reference/syncdb.md#createsyncdb-configuration)).
-
-With a token source, the hook:
-
-- reads `getToken()` on every connect and reconnect;
-- calls `refresh()` once when the server rejects the token, then reconnects, and stops after a
-  second rejection (`onConnectError` fires). With no `refresh`, or a failed one, it stops at
-  once;
-- reconnects with the new token when `onAuthChange` fires, and disconnects when there is no
-  token.
-
-To use a different source for one socket, pass it as `tokenSource`. Passing the legacy
-`getAuthToken` getter instead turns the token source off for that hook. See
-[Token source](../reference/legacy/rtk.md#token-source).
-
-### 3. Set Up Connection Hook
-
-Create a custom hook to manage the connection. A Better Auth app gates `shouldConnect` on
-`selectBetterAuthUserId` instead of the JWT user id:
-
-``````typescript
-// hooks/useWebSocket.ts
-import {useSocketConnection, baseWebsocketsUrl} from "@terreno/rtk";
-import {selectBetterAuthUserId} from "@terreno/rtk";
-import {useSelector} from "react-redux";
-import {useCallback} from "react";
-import * as Sentry from "@sentry/react-native";
-
-export const useWebSocket = () => {
-  const userId = useSelector(selectBetterAuthUserId); // JWT apps: useSelectCurrentUserId()
-  
-  const {socket, isSocketConnected} = useSocketConnection({
-    baseUrl: baseWebsocketsUrl,
-    shouldConnect: !!userId,
-    onConnect: () => {
-      console.info("[WebSocket] Connected");
-    },
-    onDisconnect: () => {
-      console.warn("[WebSocket] Disconnected");
-    },
-    onConnectError: (error) => {
-      console.error("[WebSocket] Connection error:", error.message);
-    },
-    captureEvent: (eventName, data) => {
-      Sentry.captureMessage(eventName, {
-        level: "info",
-        extra: data,
-      });
-    },
-  });
-  
-  return {socket, isSocketConnected};
-};
-``````
-
-#### Transports
-
-`useSocketConnection` starts with HTTP long-polling and upgrades to WebSocket (`transports: ["polling", "websocket"]`), so a restarting dev server does not fail the first handshake. Polling needs every request of a session to reach the same server process. Hosts without session affinity, such as Vercel Functions, need WebSocket only:
-
-``````typescript
-useSocketConnection({
-  baseUrl,
-  shouldConnect: !!userId,
-  transports: ["websocket"],
-});
-``````
-
-`@terreno/syncdb` takes the same list as `createSyncDb({socketTransports: ["websocket"]})`. Cloud Run with `--session-affinity` works with the default. See [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md).
-
-`baseWebsocketsUrl` replaces `api.` with `ws.` in the API host (`https://api.example.com` becomes `ws.example.com`), for deployments that run sockets on a separate host. If sockets are served by the API host itself, as on Vercel, pass `baseUrl` instead.
-
-### 4. Subscribe to Events in Components
-
-``````typescript
-// screens/TodoList.tsx
-import {useWebSocket} from "@/hooks/useWebSocket";
-import {useEffect, useCallback} from "react";
-
-export const TodoListScreen = () => {
-  const {data: todos, refetch} = useGetTodosQuery();
-  const {socket} = useWebSocket();
-  
-  // Subscribe to todo events
-  useEffect(() => {
-    if (!socket) return;
-    
-    // Join the todos room
-    socket.emit("subscribe:todos");
-    
-    // Handle todo created event
-    const handleTodoCreated = (todo) => {
-      console.info("New todo created:", todo);
-      refetch(); // Refresh the list
-    };
-    
-    // Handle todo updated event
-    const handleTodoUpdated = (todo) => {
-      console.info("Todo updated:", todo);
-      refetch();
-    };
-    
-    socket.on("todo:created", handleTodoCreated);
-    socket.on("todo:updated", handleTodoUpdated);
-    
-    // Cleanup
-    return () => {
-      socket.off("todo:created", handleTodoCreated);
-      socket.off("todo:updated", handleTodoUpdated);
-    };
-  }, [socket, refetch]);
-  
-  return (
-    <Page title="Todos">
-      {todos?.data.map((todo) => (
-        <TodoItem key={todo._id} todo={todo} />
-      ))}
-    </Page>
-  );
-};
-``````
-
-### 5. Show Connection Status (Optional)
-
-``````typescript
-import {useWebSocket} from "@/hooks/useWebSocket";
-import {Box, Text, Badge} from "@terreno/ui";
-
-export const ConnectionStatus = () => {
-  const {isSocketConnected} = useWebSocket();
-  
-  return (
-    <Box direction="row" gap={2} alignItems="center">
-      <Badge
-        variant={isSocketConnected.isConnected ? "success" : "error"}
-        text={isSocketConnected.isConnected ? "Connected" : "Disconnected"}
-      />
-      {!isSocketConnected.isConnected && isSocketConnected.lastDisconnectedAt && (
-        <Text size="sm" color="secondaryDark">
-          Reconnecting...
-        </Text>
-      )}
-    </Box>
-  );
-};
-``````
-
-## Advanced Patterns
-
-### Optimistic Updates with Real-time Sync
-
-``````typescript
-const [updateTodo] = usePatchTodosMutation();
-
-const handleToggle = useCallback(async (todo) => {
-  // Optimistic update
-  const completed = !todo.completed;
-  
-  try {
-    await updateTodo({
-      id: todo._id,
-      body: {completed},
-    }).unwrap();
-    
-    // Server will emit event, triggering refetch for other clients
-  } catch (error) {
-    console.error("Failed to update todo:", error);
-    // Revert optimistic update
-  }
-}, [updateTodo]);
-``````
-
-### Room-based Subscriptions
-
-``````typescript
-// Backend: User joins project-specific room
-socket.on("join:project", (projectId) => {
-  socket.join(`project:${projectId}`);
-});
-
-// Emit to project room
-io.to(`project:${projectId}`).emit("project:updated", project);
-
-// Frontend: Subscribe to project updates
-useEffect(() => {
-  if (!socket || !projectId) return;
-  
-  socket.emit("join:project", projectId);
-  socket.on("project:updated", handleProjectUpdate);
-  
-  return () => {
-    socket.off("project:updated", handleProjectUpdate);
-  };
-}, [socket, projectId]);
-``````
-
-### Presence System
-
-``````typescript
-// Backend: Track active users
-const activeUsers = new Map();
-
-io.on("connection", (socket) => {
-  const user = socket.data.user;
-  activeUsers.set(user._id, {socketId: socket.id, lastSeen: new Date()});
-  
-  io.emit("presence:update", Array.from(activeUsers.keys()));
-  
-  socket.on("disconnect", () => {
-    activeUsers.delete(user._id);
-    io.emit("presence:update", Array.from(activeUsers.keys()));
-  });
-});
-
-// Frontend: Show active users
-const [activeUsers, setActiveUsers] = useState<string[]>([]);
-
-useEffect(() => {
-  if (!socket) return;
-  
-  socket.on("presence:update", (userIds) => {
-    setActiveUsers(userIds);
-  });
-  
-  return () => {
-    socket.off("presence:update");
-  };
-}, [socket]);
-``````
-
-## Debugging
-
-Enable debug logging in your `app.json`:
-
-``````json
-{
-  "expo": {
-    "extra": {
-      "WEBSOCKETS_DEBUG": true
-    }
-  }
-}
-``````
-
-This logs:
-- Connection attempts
-- Disconnection events with reasons
-- Token refresh attempts
-- Reconnection failures
-
-## Troubleshooting
-
-### "Authentication required" error
-
-**Cause:** Token not provided or invalid.
-
-**Solution:**
-1. Ensure the token source returns a valid token: `await getTokenSource()?.getToken()` (or
-   `getAuthToken()` on a JWT app with no source registered)
-2. Check backend token verification logic
-3. Enable `WEBSOCKETS_DEBUG` to see token status
-
-### Frequent disconnections
-
-**Cause:** Token expiration, network issues, or server restarts.
-
-**Solution:**
-- `useSocketConnection` automatically reconnects (5 attempts)
-- Tokens are refreshed if expiring within 60 seconds
-- Toast notifications inform users after 9+ seconds
-- On Vercel Functions, every socket closes at the Function max duration (300s by default); see [reconnects](vercel-function-websockets.md#reconnects)
-
-### "Session ID unknown" or a 400 on `transport=polling`
-
-**Cause:** Polling requests for one session reached different server instances (no session affinity).
-
-**Solution:** Pass `transports: ["websocket"]` to `useSocketConnection` and `socketTransports: ["websocket"]` to `createSyncDb`, or enable session affinity on the host.
-
-### Events not received
-
-**Cause:** Not subscribed to the correct room, or event name mismatch.
-
-**Solution:**
-1. Verify room subscription: `socket.emit("subscribe:todos")`
-2. Check event names match between backend and frontend
-3. Use `socket.onAny((event, ...args) => console.log(event, args))` to debug
-
-### Token refresh loops
-
-**Cause:** Backend rejecting refresh token.
-
-**Solution:**
-1. Check `REFRESH_TOKEN_SECRET` matches between backend and frontend config
-2. Verify refresh token hasn't expired
-3. Check Sentry/logs for token verification errors
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `WEBSOCKET_URL` | Yes | WebSocket server URL (e.g., `wss://api.example.com`) |
-| `WEBSOCKETS_DEBUG` | No | Enable debug logging (default: false) |
-| `TOKEN_SECRET` | Yes | JWT secret for token verification (backend) |
-| `REFRESH_TOKEN_SECRET` | Yes | Refresh token secret (backend) |
-
-## Security Considerations
-
-1. **Use WSS (TLS):** Always use `wss://` in production
-2. **Validate tokens:** Always verify JWT tokens in Socket.io middleware
-3. **Room authorization:** Check user permissions before joining rooms
-4. **Rate limiting:** Implement rate limits on event emissions
-5. **Input validation:** Validate all event data on the server
-
-## Related Documentation
-
-- [@terreno/syncdb Reference](../reference/syncdb.md) — Local-first data layer (replaces RTK for synced collections)
-- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md) — RTK Query utilities during the support window
-- [Authentication Architecture](../explanation/authentication.md) — JWT system deep-dive
-- [Run Terreno WebSockets on Vercel Functions](vercel-function-websockets.md) — Vercel's WebSocket beta: transports, reconnects, cross-instance state
-- [Socket.io Documentation](https://socket.io/docs/v4/) — Official Socket.io docs

package/dist/docs/versioned/57.18.0/implementationPlans/IP_TEMPLATE.md

@@ -1,52 +0,0 @@
-# Implementation plan template
-
-Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with
-`docs/tasks/<slug>.md`. Add `**Parent IP:** [other](other.md)` only when this plan
-rides on another plan's roadmap entry instead of getting its own. A filled Parent
-IP header skips reconcile for that file. `**Roadmap:**` sets the Area / Target / Impact
-the roadmap entry is scaffolded with on merge; omit it to have them inferred.
-
-**Status:** Draft | Approved | In progress | Complete | Deferred  
-**Roadmap:** Area=`api`, Target=`Next`, Impact=`Feature`  
-**Branch:**  
-**Owner:**  
-**Created:** YYYY-MM-DD  
-
-## Goal
-
-## Non-Goals
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-
-## Architecture
-
-## Models
-
-## APIs
-
-## Notifications
-
-## UI
-
-(Admin v2: document `home.slots` — `navGlobal`, `contentTop`, `main`, `sidebar` — if applicable.)
-
-## Phases
-
-## Feature Flags & Migrations
-
-## Activity Log & User Updates
-
-## Not Included / Future Work
-
-## Files to Create / Modify
-
-## Task List
-
-Link to `docs/tasks/<slug>.md`.
-
-## Acceptance Criteria
-
-- [ ]

package/dist/docs/versioned/57.18.0/implementationPlans/README.md

@@ -1,88 +0,0 @@
-# Implementation Plans
-
-Forward-looking design docs for significant features and architectural changes to
-Terreno packages, written **before implementation**.
-
-An implementation plan (IP) is one half of a two-file pair:
-
-| File | Holds | Path |
-| ---- | ----- | ---- |
-| **IP** | Design goals, architecture, models/APIs, testing decisions, phases, acceptance criteria | `docs/implementationPlans/<slug>.md` |
-| **Task list** | The bot-consumable execution checklist for that IP | `docs/tasks/<slug>.md` |
-
-The IP is the source of truth for *what and why*; the task list is the source of truth
-for *the concrete steps*. External trackers (a GitHub roadmap issue, a Linear issue, a
-discussion thread) link **to** these files — they never replace them. See
-[`docs/tasks/README.md`](../tasks/README.md) for the task-file shape.
-
-## Status lives on each IP
-
-There is no shared `PLAN_INDEX.md`. That file caused merge conflicts the same way a
-shared changelog Unreleased section did. Status is the `**Status:**` line in each
-`docs/implementationPlans/<slug>.md` (and in `archive/` after close). List those
-directories to see what exists; this README explains the process.
-
-## When to write an IP
-
-Substantial work is planned before coding. Quick rule (full table in
-[CONTRIBUTING.md](../../CONTRIBUTING.md#when-to-write-an-implementation-plan-ip)):
-
-| Needs an IP | Does not need an IP |
-| ----------- | ------------------- |
-| New published package | Bug fix in one package |
-| New public API surface | Documentation-only change |
-| Cross-package architectural change | Small internal refactor |
-| Breaking change | Test or CI fix |
-
-## How a plan gets written and built
-
-The [`terreno-planning` plugin](../../plugins/README.md) drives the pipeline.
-
-**Grow** interviews in grilling rounds (one frontier of decisions per message, recommended
-answers, then wait). It stays on a question until the answer is executable. After the user
-confirms shared understanding it writes the two files and ends with a **standalone
-approval brief**: an orientation paragraph on where the repository is and where the change
-takes it, optional background on current state, the idea, then the plan (tasks, tracer,
-verification, risks). When grilling produced human decisions, a Decisions table with no
-row cap follows the plan, pairing each settled choice with the question that prompted it.
-If there were none, that table is omitted. The brief must stand on its own — a reviewer
-should not need the IP, the ticket, or the interview history to approve it.
-
-For a small feature, the plugin's **feature profile** uses a compact approved task
-contract: invoke Pick once; it implements one frontier task, roasts it, then picks the
-next until the list is done, then Brew and bounded Taste iterations.
-
-1. **Grow** (`terreno-1-grow`) — grill until answers are executable, then write the IP + tracer-bullet task list; end with the standalone approval brief (summary, background, idea, plan) and a full Decisions table when any exist.
-2. **Pick** (`terreno-2-pick`) — implement one approved slice via TDD, then continue the pick-roast inner loop.
-3. **Roast** (`terreno-3-roast`) — independently verify the current task, then return (`next: pick` or `next: brew`).
-4. **Brew** (`terreno-4-brew`) — commit, push, open the PR after every in-scope task has Roast `PASS`.
-5. **Taste** (`terreno-5-taste`) — react once to current CI, mergeability, and review state.
-
-The outer loop owns Grow/Brew/Taste selection, execution-state persistence, waiting,
-retries, and human/external escalation. Pick owns the inner task loop. Roast never
-invokes Pick. Each stage emits the compact machine-readable result described
-in [`plugins/terreno-planning/references/lifecycle-contract.md`](../../plugins/terreno-planning/references/lifecycle-contract.md)
-(collapsed behind a Details toggle in chat and on the PR).
-
-You can also author an IP directly with the `ip` skill; both produce the same two files.
-
-### Roadmap handoff (roadmap-enabled repos only)
-
-In repos that run a public roadmap (Discussions + a roadmap Project — currently Terreno),
-Grow hands off to `roadmap-item` once the IP is **Approved** to create or update the
-public tracking issue, and the IP header records the `Discussion:` and `Roadmap issue:`
-links. See [`docs/explanation/roadmap-process.md`](../explanation/roadmap-process.md) for
-the full IP ↔ roadmap lifecycle.
-
-In repos with **no** roadmap board (Flourish, most consumer apps), the pipeline is
-identical minus that handoff: the IP + task list are the source of truth, and Linear
-tracks execution via the IP header `Linear:` link.
-
-## Lifecycle
-
-1. **Draft** → **Approved** — IP written and reviewed (status lives in the IP header).
-2. **In progress** → **Complete** — implemented, verified, merged.
-3. **Archive** — completed IPs move to `docs/implementationPlans/archive/`.
-
-Plans that are fully implemented and now describe shipped architecture should be migrated
-to `docs/explanation/` as reference documentation.