@terreno/mcp 57.19.2 → 57.20.0

package/src/docs/resources/patterns.md

@@ -1,216 +1,269 @@
 # Terreno Patterns & Best Practices
 
+Collection CRUD is local-first: the backend syncs a collection with `syncPlugin` and a `sync`
+config on `modelRouter`, and the frontend reads and writes it with `@terreno/syncdb/react`
+(`useQuery`, `useMutate`). Generated RTK Query hooks from `openApiSdk.ts` are only for routes
+that are not synced: auth (`/auth/me`), AI, feature flags, and custom request/response actions.
+
 ## Backend Patterns
 
 ### Model Definition
 
+A synced model uses a String `_id` (offline clients mint ids), `isDeletedPlugin` (via the app's
+default plugins), and `syncPlugin`. Types live in `src/types/models/`. Every field has a
+`description`.
+
 ```typescript
+import {syncPlugin} from "@terreno/api";
 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[]>;
-}
+import type {TodoDocument, TodoModel} from "../types/models/todoTypes";
+import {addDefaultPlugins} from "./modelPlugins";
 
 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 },
+    _id: {
+      default: (): string => new mongoose.Types.ObjectId().toHexString(),
+      description: "The document id (String so offline sync clients can mint ids)",
+      type: String,
+    },
+    completed: {
+      default: false,
+      description: "Whether the todo item has been completed",
+      type: Boolean,
+    },
+    ownerId: {
+      description: "The user who owns this todo",
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    title: {
+      description: "The title of the todo item",
+      required: true,
+      trim: true,
+      type: String,
+    },
   },
-  {
-    strict: "throw",
-    toJSON: { virtuals: true },
-    toObject: { virtuals: true },
-  }
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
 );
 
+// addDefaultPlugins applies createdUpdatedPlugin, isDeletedPlugin, findExactlyOne, findOneOrNone.
 addDefaultPlugins(todoSchema);
-
-todoSchema.statics.findByOwner = async function (ownerId: string) {
-  return this.find({ ownerId });
-};
+// Stamps a per-stream _syncSeq on every write; required by the router's sync config.
+todoSchema.plugin(syncPlugin);
 
 export const Todo = mongoose.model<TodoDocument, TodoModel>("Todo", todoSchema);
 ```
 
 ### Route Setup
 
+Use the three-argument `modelRouter` and register it on `TerrenoApp` together with `SyncApp`
+and `RealtimeApp`. Sync needs a MongoDB replica set (change streams).
+
 ```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 });
-      },
-    })
-  );
-};
+import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
+import {Todo} from "../models/todo";
+import type {UserDocument} from "../types/models/userTypes";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    delete: [Permissions.IsOwner],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+  },
+  preCreate: (body, req) => ({
+    ...body,
+    ownerId: (req.user as unknown as UserDocument)?._id,
+  }),
+  queryFields: ["completed", "ownerId"],
+  queryFilter: OwnerQueryFilter,
+  sort: "-created",
+  sync: {scope: {type: "owner"}},
+});
 ```
 
 ### 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();
+Add non-CRUD endpoints as `collectionActions` or `instanceActions` on the same `modelRouter`,
+not with `router.post`. They get permissions, validation, and OpenAPI automatically.
 
-      res.json(todo);
-    } catch (error) {
-      next(error);
-    }
-  }
-);
+```typescript
+import {APIError, modelRouter, Permissions, z} from "@terreno/api";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  // ...permissions, sync, and the rest from Route Setup
+  collectionActions: {
+    bulkComplete: {
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      handler: async ({body, user}) => {
+        const result = await Todo.updateMany(
+          {_id: {$in: body.ids}, ownerId: user?._id},
+          {$set: {completed: true}}
+        );
+        return {matched: result.matchedCount, modified: result.modifiedCount};
+      },
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      handler: async ({doc}) => {
+        if (doc.completed) {
+          throw new APIError({status: 409, title: "Todo is already completed"});
+        }
+        doc.completed = true;
+        await doc.save();
+        return doc;
+      },
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+    },
+  },
+});
 ```
 
 ## Frontend Patterns
 
 ### Screen with Data Fetching
 
+Synced collections are read from the local store with `useQuery` and written with `useMutate`.
+Writes apply immediately and sync through the durable outbox: there is no loading state per
+request, no `.unwrap()`, and no refetch after a mutation. Wrap the screen (or the app) in
+`SyncDbProvider`, and do not call `mutate` until `syncDb.start()` has resolved.
+
 ```typescript
-import React, { useCallback, useState } from "react";
-import { Box, Page, Text, Button, TextField, ScrollView } from "@terreno/ui";
-import { useGetTodosQuery, useCreateTodoMutation } from "@/store/openApiSdk";
+import {generateMutationId} from "@terreno/syncdb";
+import {SyncDbProvider, useMutate, useQuery} from "@terreno/syncdb/react";
+import {Box, Button, Card, CheckBox, Heading, IconButton, Text, TextField} from "@terreno/ui";
+import {DateTime} from "luxon";
+import type React from "react";
+import {useCallback, useState} from "react";
+import {useSyncDbReady} from "@/hooks/useSyncDbReady";
+import {syncDb} from "@/store/syncdb";
+
+interface Todo {
+  _id: string;
+  completed?: boolean;
+  created: string;
+  ownerId: string;
+  title: string;
+}
 
-const TodoScreen: React.FC = () => {
-  const [newTitle, setNewTitle] = useState("");
-  const { data: todos, isLoading, error, refetch } = useGetTodosQuery({});
-  const [createTodo, { isLoading: isCreating }] = useCreateTodoMutation();
+const TodoList: React.FC = () => {
+  const isSyncDbReady = useSyncDbReady();
+  const [newTitle, setNewTitle] = useState<string>("");
+  const todos = useQuery<Todo>("todos", {sort: "-created"});
+  const {create, update, remove} = useMutate("todos");
 
-  const handleCreate = useCallback(async () => {
-    if (!newTitle.trim()) {
+  const handleCreate = useCallback((): void => {
+    const title = newTitle.trim();
+    if (!title || !isSyncDbReady) {
       return;
     }
+    // Mint the id locally so the optimistic row is addressable before the server acks it.
+    const id = generateMutationId();
+    create({data: {_id: id, completed: false, created: DateTime.now().toISO(), title}, id});
+    setNewTitle("");
+  }, [create, isSyncDbReady, newTitle]);
+
+  const handleToggle = useCallback(
+    (todo: Todo): void => {
+      update({data: {completed: !todo.completed}, id: todo._id});
+    },
+    [update]
+  );
 
-    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>
-    );
-  }
+  const handleDelete = useCallback(
+    (id: string): void => {
+      remove({id});
+    },
+    [remove]
+  );
 
   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 gap={3} padding={4} testID="todos-screen">
+      <Heading size="lg">Todos</Heading>
+      <Card>
+        <Box gap={3}>
+          <TextField
+            onChange={setNewTitle}
+            onEnter={handleCreate}
+            placeholder="New todo"
+            testID="todos-title-input"
+            title="New Todo"
+            value={newTitle}
+          />
+          <Button
+            disabled={!isSyncDbReady || !newTitle.trim()}
+            iconName="plus"
+            onClick={handleCreate}
+            testID="todos-create-button"
+            text="Add Todo"
+          />
+        </Box>
+      </Card>
+      {todos.length === 0 ? <Text testID="todos-empty-state">No todos yet</Text> : null}
+      {todos.map((todo) => (
+        <Card key={todo._id} testID={`todo-item-${todo._id}`}>
+          <Box alignItems="center" direction="row" gap={2}>
+            <Box onClick={() => handleToggle(todo)} testID={`todo-toggle-${todo._id}`}>
+              <CheckBox selected={Boolean(todo.completed)} size="md" />
+            </Box>
+            <Box flex="grow">
+              <Text>{todo.title}</Text>
             </Box>
-            <Button
-              text="Add"
-              onClick={handleCreate}
-              loading={isCreating}
-              disabled={!newTitle.trim()}
+            <IconButton
+              accessibilityLabel="Delete todo"
+              iconName="trash"
+              onClick={() => handleDelete(todo._id)}
+              testID={`todo-delete-${todo._id}`}
+              variant="destructive"
             />
           </Box>
-
-          {todos?.map((todo) => (
-            <TodoItem key={todo.id} todo={todo} />
-          ))}
-        </Box>
-      </ScrollView>
-    </Page>
+        </Card>
+      ))}
+    </Box>
   );
 };
 
-export default TodoScreen;
+const TodosScreen: React.FC = () => (
+  <SyncDbProvider client={syncDb}>
+    <TodoList />
+  </SyncDbProvider>
+);
+
+export default TodosScreen;
 ```
 
+For large lists, render `useEntityIds` in the list and `useEntity` in each row, so a change to
+one row re-renders only that row. Running `terreno-syncdb-codegen` generates typed hooks such as
+`useTodo`, `useCreateTodo`, and `useUpdateTodo` in `store/syncDbSdk.ts`, which wrap the same
+calls.
+
 ### Form with Validation
 
+A form that calls a non-synced route uses the generated RTK Query mutation and `.unwrap()`.
+Here it updates the signed-in user's profile through `PATCH /auth/me`.
+
 ```typescript
-import React, { useCallback, useState } from "react";
-import { Box, Button, TextField, EmailField, Text } from "@terreno/ui";
-import { useCreateUserMutation } from "@/store/openApiSdk";
+import {Box, Button, EmailField, TextField} from "@terreno/ui";
+import type React from "react";
+import {useCallback, useState} from "react";
+import {usePatchMeMutation} from "@/store/sdk";
 
 interface FormErrors {
   name?: string;
   email?: string;
 }
 
-const CreateUserForm: React.FC = () => {
-  const [name, setName] = useState("");
-  const [email, setEmail] = useState("");
+const ProfileForm: React.FC = () => {
+  const [name, setName] = useState<string>("");
+  const [email, setEmail] = useState<string>("");
   const [errors, setErrors] = useState<FormErrors>({});
-  const [createUser, { isLoading }] = useCreateUserMutation();
+  const [updateProfile, {isLoading}] = usePatchMeMutation();
 
   const validate = useCallback((): boolean => {
     const newErrors: FormErrors = {};
@@ -229,40 +282,43 @@ const CreateUserForm: React.FC = () => {
     return Object.keys(newErrors).length === 0;
   }, [name, email]);
 
-  const handleSubmit = useCallback(async () => {
+  const handleSubmit = useCallback(async (): Promise<void> => {
     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);
+      await updateProfile({email, name}).unwrap();
+    } catch (error: unknown) {
+      const fields = (error as {data?: {fields?: FormErrors}}).data?.fields;
+      if (fields) {
+        setErrors(fields);
       }
     }
-  }, [name, email, validate, createUser]);
+  }, [name, email, validate, updateProfile]);
 
   return (
-    <Box padding={4} gap={3}>
+    <Box gap={3} padding={4}>
       <TextField
-        label="Name"
+        errorText={errors.name}
+        onChange={setName}
+        testID="profile-name-input"
+        title="Name"
         value={name}
-        onChangeText={setName}
-        error={errors.name}
       />
       <EmailField
-        label="Email"
+        errorText={errors.email}
+        onChange={setEmail}
+        testID="profile-email-input"
+        title="Email"
         value={email}
-        onChangeText={setEmail}
-        error={errors.email}
       />
       <Button
-        text="Create User"
-        onClick={handleSubmit}
-        loading={isLoading}
         fullWidth
+        loading={isLoading}
+        onClick={handleSubmit}
+        testID="profile-save-button"
+        text="Save"
       />
     </Box>
   );
@@ -305,19 +361,24 @@ throw new APIError({
 
 ### Frontend
 
+A synced write does not return the server's answer to the caller. A rejected or conflicting
+mutation shows up in `useSyncStatus()` and `useConflicts()`; render the conflict UI from those
+hooks. Errors from
+non-synced RTK Query routes arrive on `.unwrap()`:
+
 ```typescript
 try {
   await someApiCall().unwrap();
-} catch (err: any) {
+} catch (error: unknown) {
+  const data = (error as {data?: {detail?: string; fields?: Record<string, string>}}).data;
   // Handle field-specific errors
-  if (err.data?.fields) {
-    setErrors(err.data.fields);
+  if (data?.fields) {
+    setErrors(data.fields);
     return;
   }
 
   // Handle general errors
-  const message = err.data?.detail || err.message || "An error occurred";
-  toast.error(message);
+  toast.error(data?.detail ?? "An error occurred");
 }
 ```
 

package/src/docs/resources/ui.md

@@ -100,7 +100,6 @@ import { Text, Heading, Title } from "@terreno/ui";
 import {
   TextField,
   EmailField,
-  PasswordField,
   NumberField,
   TextArea,
   SelectField,
@@ -110,19 +109,26 @@ import {
   RadioField,
 } from "@terreno/ui";
 
+// Fields share `title`, `value`, `onChange`, `errorText`, and `helperText`.
 <TextField
-  label="Name"
+  title="Name"
   value={name}
-  onChangeText={setName}
+  onChange={setName}
   placeholder="Enter your name"
-  error={errors.name}
+  errorText={errors.name}
   helperText="Your full legal name"
 />
 
+// Passwords: TextField with type="password" (adds a show/hide control).
+<TextField title="Password" type="password" value={password} onChange={setPassword} />
+
+// NumberField values are strings; type is "number" or "decimal".
+<NumberField title="Age" type="number" value={age} onChange={setAge} />
+
 <SelectField
-  label="Country"
+  title="Country"
   value={country}
-  onChangeValue={setCountry}
+  onChange={setCountry}
   options={[
     { label: "United States", value: "US" },
     { label: "Canada", value: "CA" },
@@ -130,16 +136,16 @@ import {
 />
 
 <DateTimeField
-  label="Date of Birth"
+  title="Date of Birth"
+  type="date"
   value={dob}
   onChange={setDob}
-  mode="date"
 />
 
 <BooleanField
-  label="Accept Terms"
+  title="Accept Terms"
   value={accepted}
-  onChangeValue={setAccepted}
+  onChange={setAccepted}
 />
 ```
 
@@ -202,7 +208,7 @@ import {
 ### Page & Layout
 
 ```typescript
-import { Page, SplitPage, ScrollView } from "@terreno/ui";
+import { Page, ScrollView } from "@terreno/ui";
 
 <Page
   navigation={navigation}
@@ -215,6 +221,32 @@ import { Page, SplitPage, ScrollView } from "@terreno/ui";
 </Page>
 ```
 
+List/detail screens (mail, inbox, records) use `ListDetailLayout` as a route group's
+`_layout.tsx`. Phones push the detail route; tablets and wide browsers show the list in a left
+pane beside it. The open item lives in the URL.
+
+```typescript
+import { ListDetailIndex, ListDetailLayout, useListDetail } from "@terreno/ui";
+
+// app/mail/_layout.tsx
+export const unstable_settings = { initialRouteName: "index" };
+export default () => (
+  <ListDetailLayout
+    detailHref={(id) => `/mail/${id}`}
+    indexHref="/mail"
+    list={<MailList />}
+  />
+);
+
+// app/mail/index.tsx
+export default () => <ListDetailIndex />;
+
+// MailList rows read and change the open item
+const { selectedId, select } = useListDetail();
+```
+
+Use `SplitPage` only for list/detail views without their own routes.
+
 ## Theme System
 
 ### Using Theme
@@ -253,17 +285,16 @@ radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radius3xl
 ## Utilities
 
 ```typescript
-import { useStoredState, MediaQuery, isNarrowViewport } from "@terreno/ui";
+import {isNarrowViewport, isSupportedDesktopWidth, useStoredState} from "@terreno/ui";
+import {useWindowDimensions} from "react-native";
 
 // Persist state to storage
 const [value, setValue] = useStoredState("key", defaultValue);
 
-// Responsive rendering
-<MediaQuery minWidth={768}>
-  <DesktopLayout />
-</MediaQuery>
+const {width} = useWindowDimensions();
+const isDesktopLayout = isSupportedDesktopWidth({width});
 
-// Current window is below the desktop breakpoint.
+// Current window is below the desktop floor (web lg / native xl, 1024pt).
 // isMobileDevice() is deprecated in favor of isNarrowViewport().
 if (isNarrowViewport()) {
   // Narrow-viewport code

package/src/docs/templates/bootstrap/frontend/app/(tabs)/profile.template.tsx

@@ -11,7 +11,6 @@ const ProfileScreen: React.FC = () => {
   const [updateProfile] = usePatchMeMutation();
   const [name, setName] = useState<string>("");
   const [email, setEmail] = useState<string>("");
-  const [password, setPassword] = useState<string>("");
   const [currentPassword, setCurrentPassword] = useState<string>("");
   const [saveError, setSaveError] = useState<string | null>(null);
 
@@ -75,23 +74,6 @@ const ProfileScreen: React.FC = () => {
     [currentPassword, isEmailChanged, updateProfile]
   );
 
-  const handleSavePassword = useCallback(
-    async (value: string): Promise<void> => {
-      if (!value) {
-        return;
-      }
-      setSaveError(null);
-      try {
-        await updateProfile({password: value}).unwrap();
-        setPassword("");
-      } catch (err) {
-        console.error("Error updating password:", err);
-        setSaveError("Failed to update password");
-      }
-    },
-    [updateProfile]
-  );
-
   if (isLoading) {
     return (
       <Page navigation={undefined} title="Profile">
@@ -132,14 +114,6 @@ const ProfileScreen: React.FC = () => {
                 value={currentPassword}
               />
             )}
-            <TapToEdit
-              helperText="Leave blank to keep your current password"
-              onSave={handleSavePassword}
-              setValue={setPassword}
-              title="New Password"
-              type="password"
-              value={password}
-            />
             {saveError && <Text color="error">{saveError}</Text>}
           </Box>
         </Card>