@terreno/mcp 0.21.0

package/src/docs/templates/bootstrap/backend/utils/database.template.md

@@ -0,0 +1,27 @@
+import {logger} from "@terreno/api";
+import mongoose from "mongoose";
+
+export const connectToMongoDB = async (): Promise<void> => {
+  if (mongoose.connection.readyState === 1) {
+    logger.info("Already connected to MongoDB");
+    return;
+  }
+
+  const mongoURI = process.env.MONGO_URI || "mongodb://localhost:27017/{{dbName}}";
+
+  try {
+    await mongoose.connect(mongoURI);
+    logger.info("Connected to MongoDB");
+  } catch (error: unknown) {
+    logger.error(`MongoDB connection error: ${error}`);
+    throw error;
+  }
+
+  mongoose.connection.on("error", (error: unknown) => {
+    logger.error(`MongoDB connection error: ${error}`);
+  });
+
+  mongoose.connection.on("disconnected", () => {
+    logger.warn("MongoDB disconnected");
+  });
+};

package/src/docs/templates/bootstrap/cursorrules.template.md

@@ -0,0 +1,64 @@
+# {{appDisplayName}}
+
+A full-stack application built with the Terreno framework.
+
+## Project Structure
+
+- **{{appName}}-frontend/** - Expo/React Native frontend using @terreno/ui and @terreno/rtk
+- **{{appName}}-backend/** - Express/Mongoose backend using @terreno/api
+
+## Development
+
+Uses [Bun](https://bun.sh/) as the package manager.
+
+```bash
+# Backend
+cd {{appName}}-backend && bun run dev    # Start backend on port 4000
+
+# Frontend
+cd {{appName}}-frontend && bun run web   # Start web frontend
+cd {{appName}}-frontend && bun run sdk   # Regenerate SDK after backend changes
+```
+
+## 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`)
+- 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
+
+### React Best Practices
+- Use functional components with `React.FC` type
+- Add explanatory comment above each `useEffect`
+- Wrap callbacks in `useCallback`
+- Use Redux Toolkit for state management
+
+### Backend Conventions
+- Use `modelRouter` for CRUD endpoints
+- Use `APIError` for error responses
+- Use `logger.info/warn/error/debug` for logging
+- Use `Model.findExactlyOne` or `Model.findOneOrNone` (not `Model.findOne`)
+
+### Frontend Conventions
+- Use generated SDK hooks from `@/store/openApiSdk`
+- Use @terreno/ui components (Box, Page, Button, TextField, etc.)
+- Never modify `openApiSdk.ts` manually - regenerate with `bun run sdk`
+
+## AI Assistance
+
+This project is configured to use the Terreno MCP server for AI-assisted development.
+Use the MCP tools and prompts for:
+- Generating new models and routes
+- Creating screens and forms
+- Following Terreno patterns and best practices

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

@@ -0,0 +1,42 @@
+import FontAwesome from "@expo/vector-icons/FontAwesome";
+import {Tabs} from "expo-router";
+import type React from "react";
+import {useColorScheme} from "@/components/useColorScheme";
+import Colors from "@/constants/Colors";
+
+const TabBarIcon: React.FC<{
+  name: React.ComponentProps<typeof FontAwesome>["name"];
+  color: string;
+}> = ({name, color}) => {
+  return <FontAwesome color={color} name={name} size={24} style={{marginBottom: -3}} />;
+};
+
+const TabLayout: React.FC = () => {
+  const colorScheme = useColorScheme();
+
+  return (
+    <Tabs
+      screenOptions={{
+        tabBarActiveTintColor: Colors[colorScheme ?? "light"].tint,
+      }}
+    >
+      <Tabs.Screen
+        name="index"
+        options={{
+          tabBarIcon: ({color}) => <TabBarIcon color={color} name="home" />,
+          title: "Home",
+        }}
+      />
+      <Tabs.Screen
+        name="profile"
+        options={{
+          headerShown: false,
+          tabBarIcon: ({color}) => <TabBarIcon color={color} name="user" />,
+          title: "Profile",
+        }}
+      />
+    </Tabs>
+  );
+};
+
+export default TabLayout;

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

@@ -0,0 +1,18 @@
+import {Box, Heading, Page, Text} from "@terreno/ui";
+import type React from "react";
+
+const HomeScreen: React.FC = () => {
+  return (
+    <Page navigation={undefined} title="Home">
+      <Box gap={4} padding={4}>
+        <Heading>Welcome to {{appDisplayName}}</Heading>
+        <Text>Your app is ready for development!</Text>
+        <Text color="secondary">
+          Start by adding models to the backend and screens to the frontend.
+        </Text>
+      </Box>
+    </Page>
+  );
+};
+
+export default HomeScreen;

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

@@ -0,0 +1,44 @@
+import {Box, Button, Heading, Page, Text} from "@terreno/ui";
+import type React from "react";
+import {useCallback} from "react";
+import {logout, useAppDispatch, useGetMeQuery} from "@/store";
+
+const ProfileScreen: React.FC = () => {
+  const dispatch = useAppDispatch();
+  const {data: profile, isLoading} = useGetMeQuery();
+
+  const handleLogout = useCallback((): void => {
+    dispatch(logout());
+  }, [dispatch]);
+
+  if (isLoading) {
+    return (
+      <Page navigation={undefined} title="Profile">
+        <Box padding={4}>
+          <Text>Loading...</Text>
+        </Box>
+      </Page>
+    );
+  }
+
+  return (
+    <Page navigation={undefined} title="Profile">
+      <Box gap={4} padding={4}>
+        <Heading>Profile</Heading>
+        <Box gap={2}>
+          <Text weight="bold">Name</Text>
+          <Text>{profile?.data?.name || "Not set"}</Text>
+        </Box>
+        <Box gap={2}>
+          <Text weight="bold">Email</Text>
+          <Text>{profile?.data?.email || "Not set"}</Text>
+        </Box>
+        <Box marginTop={4}>
+          <Button fullWidth onClick={handleLogout} text="Logout" variant="outline" />
+        </Box>
+      </Box>
+    </Page>
+  );
+};
+
+export default ProfileScreen;

package/src/docs/templates/bootstrap/frontend/app/+not-found.template.tsx

@@ -0,0 +1,21 @@
+import {Box, Text} from "@terreno/ui";
+import {Link, Stack} from "expo-router";
+import type React from "react";
+
+const NotFoundScreen: React.FC = () => {
+  return (
+    <>
+      <Stack.Screen options={{title: "Oops!"}} />
+      <Box alignItems="center" flex={1} justifyContent="center" padding={4}>
+        <Text size="lg" weight="bold">
+          This screen doesn't exist.
+        </Text>
+        <Link href="/" style={{marginTop: 16}}>
+          <Text color="link">Go to home screen</Text>
+        </Link>
+      </Box>
+    </>
+  );
+};
+
+export default NotFoundScreen;

package/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx

@@ -0,0 +1,71 @@
+import FontAwesome from "@expo/vector-icons/FontAwesome";
+import {DarkTheme, DefaultTheme, ThemeProvider} from "@react-navigation/native";
+import {useFonts} from "expo-font";
+import {Stack} from "expo-router";
+import * as SplashScreen from "expo-splash-screen";
+import {useEffect} from "react";
+import "react-native-reanimated";
+import {baseUrl, useSelectCurrentUserId} from "@terreno/rtk";
+import {TerrenoProvider} from "@terreno/ui";
+import {Provider} from "react-redux";
+import {PersistGate} from "redux-persist/integration/react";
+import {useColorScheme} from "@/components/useColorScheme";
+import store, {persistor} from "@/store";
+
+export {ErrorBoundary} from "expo-router";
+
+export const unstable_settings = {
+  initialRouteName: "(tabs)",
+};
+
+SplashScreen.preventAutoHideAsync();
+
+export default function RootLayout(): React.ReactElement | null {
+  const [loaded, error] = useFonts({
+    SpaceMono: require("../assets/fonts/SpaceMono-Regular.ttf"),
+    ...FontAwesome.font,
+  });
+
+  useEffect(() => {
+    if (error) {
+      throw error;
+    }
+  }, [error]);
+
+  useEffect(() => {
+    if (loaded) {
+      SplashScreen.hideAsync();
+    }
+  }, [loaded]);
+
+  if (!loaded) {
+    return null;
+  }
+
+  return (
+    <Provider store={store}>
+      <PersistGate loading={null} persistor={persistor}>
+        <TerrenoProvider openAPISpecUrl={`${baseUrl}/openapi.json`}>
+          <RootLayoutNav />
+        </TerrenoProvider>
+      </PersistGate>
+    </Provider>
+  );
+}
+
+function RootLayoutNav(): React.ReactElement {
+  const colorScheme = useColorScheme();
+  const userId = useSelectCurrentUserId();
+
+  return (
+    <ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>
+      <Stack>
+        {!userId ? (
+          <Stack.Screen name="login" options={{headerShown: false}} />
+        ) : (
+          <Stack.Screen name="(tabs)" options={{headerShown: false}} />
+        )}
+      </Stack>
+    </ThemeProvider>
+  );
+}

package/src/docs/templates/bootstrap/frontend/app/login.template.tsx

@@ -0,0 +1,116 @@
+import {Box, Button, Heading, Page, Text, TextField, useToast} from "@terreno/ui";
+import type React from "react";
+import {useCallback, useState} from "react";
+import {useEmailLoginMutation, useEmailSignUpMutation} from "@/store";
+
+const LoginScreen: React.FC = () => {
+  const [name, setName] = useState<string>("");
+  const [email, setEmail] = useState<string>("");
+  const [password, setPassword] = useState<string>("");
+  const [isSignUp, setIsSignUp] = useState<boolean>(false);
+  const toast = useToast();
+
+  const [emailLogin, {isLoading: isLoginLoading, error: loginError}] = useEmailLoginMutation();
+  const [emailSignUp, {isLoading: isSignUpLoading, error: signUpError}] = useEmailSignUpMutation();
+
+  const handleSubmit = useCallback(async (): Promise<void> => {
+    if (!email || !password) {
+      toast.warn("Email and password are required");
+      return;
+    }
+
+    if (isSignUp && !name) {
+      toast.warn("Signup requires name");
+      return;
+    }
+
+    try {
+      if (isSignUp) {
+        await emailSignUp({email, name, password}).unwrap();
+      } else {
+        await emailLogin({email, password}).unwrap();
+      }
+    } catch (err) {
+      console.error("Authentication error:", err);
+    }
+  }, [email, password, name, isSignUp, emailLogin, emailSignUp, toast]);
+
+  const toggleMode = useCallback((): void => {
+    setIsSignUp(!isSignUp);
+  }, [isSignUp]);
+
+  const isLoading = isLoginLoading || isSignUpLoading;
+  const error = loginError || signUpError;
+  const isSubmitDisabled = !email || !password || (isSignUp && !name) || isLoading;
+
+  return (
+    <Page navigation={undefined}>
+      <Box
+        alignItems="center"
+        alignSelf="center"
+        flex="grow"
+        justifyContent="center"
+        maxWidth={400}
+        padding={4}
+        width="100%"
+      >
+        <Box marginBottom={8}>
+          <Heading>{isSignUp ? "Create Account" : "Welcome Back"}</Heading>
+        </Box>
+        <Box gap={4} width="100%">
+          {isSignUp && (
+            <TextField
+              disabled={isLoading}
+              onChange={setName}
+              placeholder="Name"
+              title="Name"
+              value={name}
+            />
+          )}
+          <TextField
+            autoComplete="off"
+            disabled={isLoading}
+            onChange={setEmail}
+            placeholder="Email"
+            title="Email"
+            type="email"
+            value={email}
+          />
+          <TextField
+            disabled={isLoading}
+            onChange={setPassword}
+            placeholder="Password"
+            title="Password"
+            type="password"
+            value={password}
+          />
+          {Boolean(error) && (
+            <Text color="error">
+              {(error as {data?: {message?: string}})?.data?.message || "An error occurred"}
+            </Text>
+          )}
+          <Box marginTop={4}>
+            <Button
+              disabled={isSubmitDisabled}
+              fullWidth
+              loading={isLoading}
+              onClick={handleSubmit}
+              text={isSignUp ? "Sign Up" : "Login"}
+            />
+          </Box>
+          <Box marginTop={2}>
+            <Button
+              disabled={isLoading}
+              fullWidth
+              onClick={toggleMode}
+              text={isSignUp ? "Already have an account? Login" : "Need an account? Sign Up"}
+              variant="outline"
+            />
+          </Box>
+        </Box>
+      </Box>
+    </Page>
+  );
+};
+
+export default LoginScreen;

package/src/docs/templates/bootstrap/frontend/components/useColorScheme.template.md

@@ -0,0 +1 @@
+export {useColorScheme} from "react-native";

package/src/docs/templates/bootstrap/frontend/constants/Colors.template.md

@@ -0,0 +1,21 @@
+const tintColorLight = "#0a7ea4";
+const tintColorDark = "#fff";
+
+export default {
+  dark: {
+    background: "#151718",
+    icon: "#9BA1A6",
+    tabIconDefault: "#9BA1A6",
+    tabIconSelected: tintColorDark,
+    text: "#ECEDEE",
+    tint: tintColorDark,
+  },
+  light: {
+    background: "#fff",
+    icon: "#687076",
+    tabIconDefault: "#687076",
+    tabIconSelected: tintColorLight,
+    text: "#11181C",
+    tint: tintColorLight,
+  },
+};

package/src/docs/templates/bootstrap/frontend/openapi-config.template.md

@@ -0,0 +1,16 @@
+import type {ConfigFile} from "@rtk-query/codegen-openapi";
+
+const config: ConfigFile = {
+  apiFile: "@terreno/rtk",
+  apiImport: "emptySplitApi",
+  argSuffix: "Args",
+  exportName: "openapi",
+  flattenArg: true,
+  hooks: true,
+  outputFile: "./store/openApiSdk.ts",
+  responseSuffix: "Res",
+  schemaFile: process.env.OPENAPI_URL ?? "http://localhost:4000/openapi.json",
+  tag: true,
+};
+
+export default config;

package/src/docs/templates/bootstrap/frontend/scripts/generate-sdk.template.md

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+
+import {exec} from "node:child_process";
+import {existsSync, readFileSync, writeFileSync} from "node:fs";
+import {join} from "node:path";
+
+const cliPath = join(
+  __dirname,
+  "..",
+  "node_modules",
+  "@rtk-query",
+  "codegen-openapi",
+  "lib",
+  "bin",
+  "cli.mjs"
+);
+const configPath = join(__dirname, "..", "openapi-config.ts");
+const tsConfigPath = join(__dirname, "..", "tsconfig.codegen.json");
+
+const command = `TS_NODE_PROJECT=${tsConfigPath} tsx ${cliPath} ${configPath}`;
+
+exec(command, (error, _stdout, stderr) => {
+  if (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+  if (stderr) {
+    console.error(`stderr: ${stderr}`);
+  }
+
+  const sdkPath = join(__dirname, "..", "store", "openApiSdk.ts");
+
+  if (existsSync(sdkPath)) {
+    let content = readFileSync(sdkPath, "utf8");
+    content = content.replace(/^export const \{\} = injectedRtkApi;\n?/m, "");
+    writeFileSync(sdkPath, content, "utf8");
+  }
+
+  exec(
+    "bunx biome check --unsafe --write store/openApiSdk.ts",
+    {cwd: join(__dirname, "..")},
+    (formatError) => {
+      if (formatError) {
+        console.error(`Formatting error: ${formatError.message}`);
+        process.exit(1);
+      }
+    }
+  );
+});

package/src/docs/templates/bootstrap/frontend/store/appState.template.md

@@ -0,0 +1,45 @@
+import {createSlice, type PayloadAction} from "@reduxjs/toolkit";
+import type {RootState} from "@terreno/rtk";
+import {type TypedUseSelectorHook, useSelector} from "react-redux";
+
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+
+export type AppState = {
+  darkMode: boolean;
+  language: string;
+};
+
+const initialState: AppState = {
+  darkMode: false,
+  language: "en",
+};
+
+export const appStateSlice = createSlice({
+  initialState,
+  name: "appState",
+  reducers: {
+    resetAppState: () => initialState,
+    setDarkMode: (state, action: PayloadAction<boolean>) => {
+      state.darkMode = action.payload;
+    },
+    setLanguage: (state, action: PayloadAction<string>) => {
+      state.language = action.payload;
+    },
+  },
+});
+
+export const {setDarkMode, setLanguage, resetAppState} = appStateSlice.actions;
+
+export const useSelectDarkMode = (): boolean => {
+  return useAppSelector((state: RootState): boolean => {
+    return state.appState.darkMode;
+  });
+};
+
+export const useSelectLanguage = (): string => {
+  return useAppSelector((state: RootState): string => {
+    return state.appState.language;
+  });
+};
+
+export default appStateSlice.reducer;

package/src/docs/templates/bootstrap/frontend/store/errors.template.md

@@ -0,0 +1,51 @@
+import type {Middleware} from "@reduxjs/toolkit";
+import {useToast} from "@terreno/ui";
+
+const ignoredErrors = [
+  "Password or username is incorrect",
+  "Token refresh failed with 401",
+  "Failed to refresh token",
+];
+
+// biome-ignore lint/suspicious/noExplicitAny: Generic middleware
+export const rtkQueryErrorMiddleware: Middleware = () => (next) => (action: any) => {
+  if (action?.error && action?.payload) {
+    const errorMessage =
+      action.payload?.data?.title ??
+      action.payload?.data?.message ??
+      action.payload?.error ??
+      JSON.stringify(action.payload);
+
+    let endpointInfo = "unknown endpoint";
+    if (action.meta?.baseQueryMeta?.request?.method && action.meta?.baseQueryMeta?.request?.url) {
+      endpointInfo = `${action.meta.baseQueryMeta.request.url} ${action.meta.baseQueryMeta.request.method}`;
+    } else if (action.meta?.arg?.endpointName) {
+      endpointInfo = `${action.meta.arg.endpointName} rejected ${action.meta.arg.type || ""}`;
+    }
+
+    const message = `${endpointInfo.trim()}: ${errorMessage}`;
+    console.debug(message);
+
+    if (action.payload.status === 404 || action.payload.status === 401) {
+      return next(action);
+    }
+
+    const shouldIgnore = ignoredErrors.some((err) => errorMessage.includes(err));
+    if (!shouldIgnore) {
+      console.warn(message);
+    }
+  }
+
+  return next(action);
+};
+
+export const useSentryAndToast = (): ((errorMessage: string) => void) => {
+  const toast = useToast();
+  return (error: string): void => {
+    if (!error) {
+      return;
+    }
+    toast.error(error);
+    console.warn(`Error: ${error}`);
+  };
+};

package/src/docs/templates/bootstrap/frontend/store/index.template.md

@@ -0,0 +1,91 @@
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import {combineReducers, configureStore} from "@reduxjs/toolkit";
+import {generateAuthSlice} from "@terreno/rtk";
+import {DateTime} from "luxon";
+import {useDispatch} from "react-redux";
+import type {Storage} from "redux-persist";
+import {persistReducer, persistStore} from "redux-persist";
+
+import appState from "./appState";
+import {rtkQueryErrorMiddleware} from "./errors";
+import {terrenoApi} from "./sdk";
+
+export * from "./appState";
+export {useSentryAndToast} from "./errors";
+
+const authSlice = generateAuthSlice(terrenoApi);
+
+export const {logout} = authSlice;
+
+const createSafeStorage = (): Storage => {
+  return {
+    getItem: async (key: string): Promise<string | null> => {
+      if (typeof window !== "undefined") {
+        return AsyncStorage.getItem(key);
+      }
+      return null;
+    },
+    removeItem: async (key: string): Promise<void> => {
+      if (typeof window !== "undefined") {
+        return AsyncStorage.removeItem(key);
+      }
+    },
+    setItem: async (key: string, value: string): Promise<void> => {
+      if (typeof window !== "undefined") {
+        return AsyncStorage.setItem(key, value);
+      }
+    },
+  };
+};
+
+const persistConfig = {
+  blacklist: ["terreno-rtk"],
+  key: "root",
+  storage: createSafeStorage(),
+  timeout: 0,
+  version: 1,
+};
+
+const rootReducer = combineReducers({
+  appState,
+  auth: authSlice.authReducer,
+  "terreno-rtk": terrenoApi.reducer,
+});
+
+const persistedReducer = persistReducer(persistConfig, rootReducer);
+
+const store = configureStore({
+  devTools: process.env.NODE_ENV !== "production" && {
+    name: `App-${
+      typeof window !== "undefined"
+        // biome-ignore lint/suspicious/noAssignInExpressions: Window name assignment
+        ? window.name || ((window.name = `Window-${DateTime.now().toFormat("HH:mm:ss")}`))
+        : "Unknown"
+    }`,
+  },
+  middleware: (getDefaultMiddleware) => {
+    return getDefaultMiddleware({
+      immutableCheck: false,
+      serializableCheck: false,
+      thunk: true,
+    }).concat([
+      ...authSlice.middleware,
+      // biome-ignore lint/suspicious/noExplicitAny: RTK Query middleware typing
+      terrenoApi.middleware as any,
+      rtkQueryErrorMiddleware,
+      // biome-ignore lint/suspicious/noExplicitAny: Middleware array typing
+    ]) as any;
+  },
+  reducer: persistedReducer,
+});
+
+export const persistor = persistStore(store);
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
+
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export {useAppSelector} from "./appState";
+
+export default store;
+export * from "./sdk";