@terreno/mcp 0.21.0

package/dist/docs/resources/overview.md

@@ -0,0 +1,48 @@
+# Terreno Overview
+
+A monorepo containing shared packages for building full-stack applications with React Native and Express/Mongoose.
+
+## Packages
+
+- **@terreno/api** - REST API framework built on Express/Mongoose
+- **@terreno/ui** - React Native UI component library
+- **@terreno/rtk** - Redux Toolkit Query utilities for API backends
+
+## Development
+
+Uses [Bun](https://bun.sh/) as the package manager. Use `bun` commands, not `npm`.
+
+```bash
+bun install              # Install dependencies
+bun run compile          # Compile all packages
+bun run lint             # Lint all packages
+bun run lint:fix         # Fix lint issues
+bun run test             # Run tests in api and ui
+```
+
+## Code Style
+
+### TypeScript/JavaScript
+- Use ES module syntax and TypeScript for all code
+- Prefer interfaces over types; avoid enums, use maps
+- Prefer const arrow functions over `function` keyword
+- Use descriptive variable names with auxiliary verbs (e.g., `isLoading`)
+- Use camelCase directories (e.g., `components/authWizard`)
+- Favor named exports
+- Use the RORO pattern (Receive an Object, Return an Object)
+
+### Dates and Time
+- Always use Luxon instead of Date or dayjs
+
+### Error Handling
+- Check error conditions at start of functions and return early
+- Limit nested if statements
+- Use multiline syntax with curly braces for all conditionals
+
+### Testing
+- Use bun test with expect for testing
+
+### Logging
+- Frontend: Use `console.info`, `console.debug`, `console.warn`, or `console.error` for permanent logs
+- Backend: Use `logger.info/warn/error/debug` for permanent logs
+- Use `console.log` only for debugging (to be removed)

package/dist/docs/resources/patterns.md

@@ -0,0 +1,338 @@
+# Terreno Patterns & Best Practices
+
+## Backend Patterns
+
+### Model Definition
+
+```typescript
+import mongoose from "mongoose";
+import { addDefaultPlugins } from "@terreno/api";
+
+interface TodoDocument extends mongoose.Document {
+  title: string;
+  completed: boolean;
+  ownerId: mongoose.Types.ObjectId;
+  created: Date;
+  updated: Date;
+}
+
+interface TodoModel extends mongoose.Model<TodoDocument> {
+  findByOwner(ownerId: string): Promise<TodoDocument[]>;
+}
+
+const todoSchema = new mongoose.Schema<TodoDocument, TodoModel>(
+  {
+    title: { type: String, required: true, trim: true },
+    completed: { type: Boolean, default: false },
+    ownerId: { type: mongoose.Schema.Types.ObjectId, ref: "User", required: true },
+  },
+  {
+    strict: "throw",
+    toJSON: { virtuals: true },
+    toObject: { virtuals: true },
+  }
+);
+
+addDefaultPlugins(todoSchema);
+
+todoSchema.statics.findByOwner = async function (ownerId: string) {
+  return this.find({ ownerId });
+};
+
+export const Todo = mongoose.model<TodoDocument, TodoModel>("Todo", todoSchema);
+```
+
+### Route Setup
+
+```typescript
+import { Router } from "express";
+import { modelRouter, Permissions, OwnerQueryFilter } from "@terreno/api";
+import { Todo, TodoDocument } from "../models/todo";
+import { UserDocument } from "../models/user";
+
+export const addTodoRoutes = (router: Router) => {
+  router.use(
+    "/todos",
+    modelRouter(Todo, {
+      permissions: {
+        create: [Permissions.IsAuthenticated],
+        list: [Permissions.IsAuthenticated],
+        read: [Permissions.IsOwner],
+        update: [Permissions.IsOwner],
+        delete: [Permissions.IsOwner],
+      },
+      queryFields: ["completed"],
+      queryFilter: OwnerQueryFilter,
+      sort: "-created",
+      preCreate: (body, req) => ({
+        ...body,
+        ownerId: (req.user as UserDocument)?._id,
+      }),
+      postCreate: async (todo, req) => {
+        // Send notification, update stats, etc.
+        logger.info("Todo created", { todoId: todo._id });
+      },
+    })
+  );
+};
+```
+
+### Custom Endpoints
+
+```typescript
+import { createOpenApiBuilder, APIError, authenticateMiddleware } from "@terreno/api";
+
+const toggleCompleteBuilder = createOpenApiBuilder()
+  .withTags(["Todos"])
+  .withSummary("Toggle todo completion status")
+  .withResponse(200, TodoSchema);
+
+router.post(
+  "/todos/:id/toggle",
+  authenticateMiddleware,
+  toggleCompleteBuilder.build(),
+  async (req, res, next) => {
+    try {
+      const todo = await Todo.findOneOrThrow({ _id: req.params.id });
+
+      if (!todo.ownerId.equals((req.user as UserDocument)._id)) {
+        throw new APIError({
+          status: 403,
+          title: "Forbidden",
+          detail: "You do not own this todo",
+        });
+      }
+
+      todo.completed = !todo.completed;
+      await todo.save();
+
+      res.json(todo);
+    } catch (error) {
+      next(error);
+    }
+  }
+);
+```
+
+## Frontend Patterns
+
+### Screen with Data Fetching
+
+```typescript
+import React, { useCallback, useState } from "react";
+import { Box, Page, Text, Button, TextField, ScrollView } from "@terreno/ui";
+import { useGetTodosQuery, useCreateTodoMutation } from "@/store/openApiSdk";
+
+const TodoScreen: React.FC = () => {
+  const [newTitle, setNewTitle] = useState("");
+  const { data: todos, isLoading, error, refetch } = useGetTodosQuery({});
+  const [createTodo, { isLoading: isCreating }] = useCreateTodoMutation();
+
+  const handleCreate = useCallback(async () => {
+    if (!newTitle.trim()) {
+      return;
+    }
+
+    try {
+      await createTodo({ title: newTitle }).unwrap();
+      setNewTitle("");
+    } catch (err) {
+      console.error("Failed to create todo:", err);
+    }
+  }, [newTitle, createTodo]);
+
+  if (isLoading) {
+    return (
+      <Page navigation={undefined}>
+        <Box flex={1} alignItems="center" justifyContent="center">
+          <Text>Loading...</Text>
+        </Box>
+      </Page>
+    );
+  }
+
+  if (error) {
+    return (
+      <Page navigation={undefined}>
+        <Box flex={1} alignItems="center" justifyContent="center" gap={2}>
+          <Text color="error500">Failed to load todos</Text>
+          <Button text="Retry" onClick={refetch} />
+        </Box>
+      </Page>
+    );
+  }
+
+  return (
+    <Page navigation={undefined} title="Todos">
+      <ScrollView>
+        <Box padding={4} gap={3}>
+          <Box direction="row" gap={2}>
+            <Box flex={1}>
+              <TextField
+                placeholder="New todo..."
+                value={newTitle}
+                onChangeText={setNewTitle}
+              />
+            </Box>
+            <Button
+              text="Add"
+              onClick={handleCreate}
+              loading={isCreating}
+              disabled={!newTitle.trim()}
+            />
+          </Box>
+
+          {todos?.map((todo) => (
+            <TodoItem key={todo.id} todo={todo} />
+          ))}
+        </Box>
+      </ScrollView>
+    </Page>
+  );
+};
+
+export default TodoScreen;
+```
+
+### Form with Validation
+
+```typescript
+import React, { useCallback, useState } from "react";
+import { Box, Button, TextField, EmailField, Text } from "@terreno/ui";
+import { useCreateUserMutation } from "@/store/openApiSdk";
+
+interface FormErrors {
+  name?: string;
+  email?: string;
+}
+
+const CreateUserForm: React.FC = () => {
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [createUser, { isLoading }] = useCreateUserMutation();
+
+  const validate = useCallback((): boolean => {
+    const newErrors: FormErrors = {};
+
+    if (!name.trim()) {
+      newErrors.name = "Name is required";
+    }
+
+    if (!email.trim()) {
+      newErrors.email = "Email is required";
+    } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      newErrors.email = "Invalid email format";
+    }
+
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [name, email]);
+
+  const handleSubmit = useCallback(async () => {
+    if (!validate()) {
+      return;
+    }
+
+    try {
+      await createUser({ name, email }).unwrap();
+      // Success - navigate or show message
+    } catch (err: any) {
+      if (err.data?.fields) {
+        setErrors(err.data.fields);
+      }
+    }
+  }, [name, email, validate, createUser]);
+
+  return (
+    <Box padding={4} gap={3}>
+      <TextField
+        label="Name"
+        value={name}
+        onChangeText={setName}
+        error={errors.name}
+      />
+      <EmailField
+        label="Email"
+        value={email}
+        onChangeText={setEmail}
+        error={errors.email}
+      />
+      <Button
+        text="Create User"
+        onClick={handleSubmit}
+        loading={isLoading}
+        fullWidth
+      />
+    </Box>
+  );
+};
+```
+
+## Error Handling
+
+### Backend
+
+```typescript
+import { APIError } from "@terreno/api";
+
+// Validation error with field-specific messages
+throw new APIError({
+  status: 400,
+  title: "Validation Error",
+  detail: "Please fix the following errors",
+  code: "VALIDATION_ERROR",
+  fields: {
+    email: "Email already exists",
+    password: "Password must be at least 8 characters",
+  },
+});
+
+// Not found
+throw new APIError({
+  status: 404,
+  title: "Not Found",
+  detail: "The requested resource was not found",
+});
+
+// Permission denied
+throw new APIError({
+  status: 403,
+  title: "Forbidden",
+  detail: "You do not have permission to perform this action",
+});
+```
+
+### Frontend
+
+```typescript
+try {
+  await someApiCall().unwrap();
+} catch (err: any) {
+  // Handle field-specific errors
+  if (err.data?.fields) {
+    setErrors(err.data.fields);
+    return;
+  }
+
+  // Handle general errors
+  const message = err.data?.detail || err.message || "An error occurred";
+  toast.error(message);
+}
+```
+
+## Code Style Checklist
+
+- [ ] Use ES module syntax
+- [ ] Use const arrow functions
+- [ ] Use Luxon for dates
+- [ ] Use interfaces over types
+- [ ] No enums (use maps)
+- [ ] Named exports preferred
+- [ ] RORO pattern for complex functions
+- [ ] Early returns for error conditions
+- [ ] No nested if statements (prefer early return)
+- [ ] Multiline syntax with braces for conditionals
+- [ ] `console.log` only for debugging
+- [ ] Wrap callbacks with useCallback
+- [ ] Provide explicit return types

package/dist/docs/resources/rtk.md

@@ -0,0 +1,179 @@
+# @terreno/rtk Documentation
+
+Redux Toolkit Query utilities for frontends connecting to @terreno/api backends.
+
+## Key Exports
+
+- `emptyApi` - Base RTK Query API configured with axios
+- `authSlice` - Redux slice for auth state
+- `generateProfileEndpoints` - Auth endpoint builder
+- Token utilities: `getTokenExpirationTimes()`, `getFriendlyExpirationInfo()`, `getAuthToken()`
+
+## Setup
+
+### Store Configuration
+
+```typescript
+import { configureStore } from "@reduxjs/toolkit";
+import { emptyApi, authSlice } from "@terreno/rtk";
+import { openApiSdk } from "./openApiSdk";
+
+export const store = configureStore({
+  reducer: {
+    [openApiSdk.reducerPath]: openApiSdk.reducer,
+    auth: authSlice.reducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(openApiSdk.middleware),
+});
+```
+
+### SDK Generation
+
+The SDK is auto-generated from your backend's OpenAPI spec:
+
+```typescript
+// openApiSdk.ts - AUTO-GENERATED, DO NOT EDIT
+import { emptyApi } from "@terreno/rtk";
+
+export const openApiSdk = emptyApi.injectEndpoints({
+  endpoints: (build) => ({
+    getUsers: build.query<User[], GetUsersParams>({
+      query: (params) => ({ url: "/users", params }),
+    }),
+    createUser: build.mutation<User, CreateUserBody>({
+      query: (body) => ({ url: "/users", method: "POST", body }),
+    }),
+  }),
+});
+
+export const { useGetUsersQuery, useCreateUserMutation } = openApiSdk;
+```
+
+## Using the SDK
+
+```typescript
+import { useGetUsersQuery, useCreateUserMutation } from "@/store/openApiSdk";
+
+const UserList = () => {
+  const { data: users, isLoading, error } = useGetUsersQuery({ limit: 10 });
+  const [createUser, { isLoading: isCreating }] = useCreateUserMutation();
+
+  const handleCreate = async () => {
+    try {
+      const newUser = await createUser({ name: "John", email: "john@example.com" }).unwrap();
+      console.info("Created user:", newUser);
+    } catch (err) {
+      console.error("Failed to create user:", err);
+    }
+  };
+
+  if (isLoading) return <Text>Loading...</Text>;
+  if (error) return <Text>Error loading users</Text>;
+
+  return (
+    <Box>
+      {users?.map((user) => (
+        <Text key={user.id}>{user.name}</Text>
+      ))}
+      <Button text="Add User" onClick={handleCreate} loading={isCreating} />
+    </Box>
+  );
+};
+```
+
+## Authentication
+
+### Login
+
+```typescript
+import { useEmailLoginMutation } from "@/store/openApiSdk";
+import { useAppDispatch } from "@/store";
+import { authSlice } from "@terreno/rtk";
+
+const LoginScreen = () => {
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [emailLogin, { isLoading, error }] = useEmailLoginMutation();
+  const dispatch = useAppDispatch();
+
+  const handleLogin = async () => {
+    try {
+      const result = await emailLogin({ email, password }).unwrap();
+      // Auth state is automatically updated
+    } catch (err) {
+      console.error("Login failed:", err);
+    }
+  };
+
+  return (
+    <Box padding={4} gap={3}>
+      <EmailField label="Email" value={email} onChangeText={setEmail} />
+      <PasswordField label="Password" value={password} onChangeText={setPassword} />
+      <Button text="Login" onClick={handleLogin} loading={isLoading} />
+    </Box>
+  );
+};
+```
+
+### Auth State
+
+```typescript
+import { useAppSelector } from "@/store";
+
+const Component = () => {
+  const userId = useAppSelector((state) => state.auth.userId);
+  const isAuthenticated = !!userId;
+
+  // ...
+};
+```
+
+### Logout
+
+```typescript
+import { LOGOUT_ACTION_TYPE } from "@terreno/rtk";
+
+const handleLogout = () => {
+  dispatch({ type: LOGOUT_ACTION_TYPE });
+};
+```
+
+## Token Management
+
+Tokens are automatically managed:
+- Stored in `expo-secure-store` (mobile) or AsyncStorage (web)
+- Auto-refresh with exponential backoff
+- Mutex-protected to prevent race conditions
+
+```typescript
+import { getAuthToken, getTokenExpirationTimes } from "@terreno/rtk";
+
+// Get current token
+const token = await getAuthToken();
+
+// Check expiration
+const { accessTokenExpiry, refreshTokenExpiry } = getTokenExpirationTimes(token);
+```
+
+## Platform Detection
+
+```typescript
+import { IsWeb, IsNative } from "@terreno/rtk";
+
+if (IsWeb) {
+  // Web-specific code
+}
+
+if (IsNative) {
+  // Mobile-specific code
+}
+```
+
+## Best Practices
+
+1. **Never use axios directly** - Always use generated SDK hooks
+2. **Don't modify generated SDK** - It's auto-generated from OpenAPI spec
+3. **Use .unwrap()** for mutations to get the result or throw error
+4. **Handle loading and error states** in your UI
+5. **Use TypeScript** - The SDK provides full type safety