@terreno/mcp 0.21.0

package/src/docs/versioned/next/how-to/upgrade-banner.md

@@ -0,0 +1,172 @@
+# Upgrade Banner
+
+Two-tier system for notifying users about app updates: a soft warning (dismissible toast) and a hard block (full-screen, no dismiss). Admin-configurable thresholds per platform.
+
+## How It Works
+
+1. **Backend** exposes `GET /version-check?version=N&platform=web|mobile` (public, no auth)
+2. **Admin** configures version thresholds via the admin panel
+3. **Client** calls `useUpgradeCheck()` on mount, which compares the app's build number against the thresholds
+4. Result: `ok` (no action), `warning` (persistent toast), or `required` (blocking screen)
+
+## Setup
+
+### 1. Backend: Register the VersionCheckPlugin
+
+```typescript
+import {TerrenoApp, VersionCheckPlugin} from "@terreno/api";
+
+const app = new TerrenoApp({userModel: User})
+  .register(new VersionCheckPlugin())
+  .start();
+```
+
+This adds the public `GET /version-check` endpoint. The admin routes (`GET/PUT /admin/version-config`) are automatically available if you're using `AdminApp`.
+
+### 2. Frontend: Add build number injection
+
+Create or update `app.config.ts` in your Expo app root. Use the `resolveBuildNumber` helper from `@terreno/rtk/buildNumber`:
+
+```typescript
+import {resolveBuildNumber} from "@terreno/rtk/buildNumber";
+import type {ConfigContext, ExpoConfig} from "expo/config";
+
+export default ({config}: ConfigContext): ExpoConfig => ({
+  ...config,
+  extra: {
+    ...config.extra,
+    buildNumber: resolveBuildNumber({configValue: config.extra?.buildNumber}),
+  },
+} as ExpoConfig);
+```
+
+`resolveBuildNumber` resolves the build number in this order:
+
+1. **`override`** option (set to a number for local testing)
+2. **`configValue`** option (e.g. from `app.json` `expo.extra.buildNumber` or EAS Build)
+3. **`EXPO_PUBLIC_BUILD_NUMBER`** env var (customizable via `envVar` option)
+4. **`git rev-list --count HEAD`** (default)
+5. **`undefined`** if git is unavailable (version check will be skipped)
+
+This sets `Constants.expoConfig.extra.buildNumber` when Metro loads the config. By default it tracks the git commit count.
+
+**If you change `buildNumber` and nothing updates:** restart the dev server (`bun expo start` or `expo start --clear`). `expo-constants` is filled when the bundle is built; hot reload does not always re-read `app.config.ts`.
+
+### 3. Frontend: Wire up the hook
+
+In your root layout:
+
+```typescript
+import {useUpgradeCheck} from "@terreno/rtk";
+import {UpgradeRequiredScreen} from "@terreno/ui";
+
+function RootLayoutNav() {
+  const {isRequired, requiredMessage, onUpdate} = useUpgradeCheck();
+
+  if (isRequired) {
+    return (
+      <UpgradeRequiredScreen
+        message={requiredMessage ?? "Please update to continue."}
+        onUpdate={onUpdate}
+      />
+    );
+  }
+
+  return <Stack>{/* normal routes */}</Stack>;
+}
+```
+
+The hook handles:
+- **ok**: Nothing happens, app runs normally
+- **warning**: Shows a persistent toast with the admin-configured message
+- **required**: Returns `isRequired: true` so you can render the blocking screen
+- **No build number**: Skips the check entirely (dev environment)
+
+### 4. Admin: Configure thresholds
+
+Navigate to the admin panel and select "Version Config". Set:
+
+- **Web Warning Version**: Build number below which web users see a warning toast
+- **Web Required Version**: Build number below which web users are blocked
+- **Mobile Warning Version**: Same for mobile
+- **Mobile Required Version**: Same for mobile
+- **Warning Message**: Text shown in the toast
+- **Required Message**: Text shown on the blocking screen
+- **Update URL** (optional): App store or download link for mobile updates
+
+All version fields default to `0`, meaning no constraint until configured.
+
+## CI/CD: Build Number in GitHub Actions
+
+### EAS Build
+
+In your `eas.json`, use a pre-build hook or set the build number via environment:
+
+```yaml
+# .github/workflows/build.yml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for git rev-list --count
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build with EAS
+        run: eas build --platform all --non-interactive
+```
+
+Since `app.config.ts` runs `git rev-list --count HEAD` at build time, the build number is automatically set. The key requirement is `fetch-depth: 0` in the checkout step to ensure the full git history is available.
+
+### Web Deployments
+
+For static web builds (e.g. `expo export`):
+
+```yaml
+jobs:
+  deploy-web:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Export web build
+        run: npx expo export --platform web
+
+      - name: Deploy
+        run: # your deployment step
+```
+
+The `app.config.ts` runs during `expo export`, so the build number is embedded in the static output.
+
+### Verifying the Build Number
+
+After building, you can verify the build number is set correctly:
+
+```bash
+# Check the current commit count locally
+git rev-list --count HEAD
+```
+
+This number should match what `Constants.expoConfig.extra.buildNumber` returns in the running app.
+
+## Architecture
+
+```
+App mounts → useUpgradeCheck() fires
+  → GET /version-check?version=N&platform=web|mobile
+  → "ok"       → normal app
+  → "warning"  → normal app + persistent toast
+  → "required" → UpgradeRequiredScreen (blocks everything)
+```
+
+Update behavior when user taps "Update":
+- **Web**: `window.location.reload()` — picks up the latest deployment
+- **Mobile**: Opens `updateUrl` via `Linking.openURL()` (e.g. App Store link)

package/src/docs/versioned/next/how-to/websocket-integration.md

@@ -0,0 +1,416 @@
+# 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. Set Up Connection Hook
+
+Create a custom hook to manage the connection:
+
+``````typescript
+// hooks/useWebSocket.ts
+import {useSocketConnection, getAuthToken, baseWebsocketsUrl} from "@terreno/rtk";
+import {useSelectCurrentUserId} from "@/store";
+import {useCallback} from "react";
+import * as Sentry from "@sentry/react-native";
+
+export const useWebSocket = () => {
+  const userId = useSelectCurrentUserId();
+  
+  const {socket, isSocketConnected} = useSocketConnection({
+    baseUrl: baseWebsocketsUrl,
+    shouldConnect: !!userId,
+    getAuthToken,
+    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};
+};
+``````
+
+### 3. 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>
+  );
+};
+``````
+
+### 4. 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 `getAuthToken()` returns a valid JWT
+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
+
+### 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/rtk Reference](../reference/rtk.md) — Full API documentation
+- [Authentication Architecture](../explanation/authentication.md) — JWT system deep-dive
+- [Socket.io Documentation](https://socket.io/docs/v4/) — Official Socket.io docs

package/src/docs/versioned/next/implementationPlans/IP_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Implementation plan template
+
+Copy to `docs/implementationPlans/<slug>.md` and replace placeholders. Pair with `docs/tasks/<slug>.md`.
+
+**Status:** Draft | Approved | In progress | Complete | Deferred  
+**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
+
+- [ ]