@terreno/mcp 0.21.0

package/dist/docs/resources/ui.md

@@ -0,0 +1,288 @@
+# @terreno/ui Documentation
+
+Comprehensive React Native UI component library with cross-platform support (web, iOS, Android).
+
+## Installation
+
+```bash
+bun add @terreno/ui
+```
+
+## Setup
+
+Wrap your app with TerrenoProvider:
+
+```typescript
+import { TerrenoProvider } from "@terreno/ui";
+
+const App = () => (
+  <TerrenoProvider>
+    <YourApp />
+  </TerrenoProvider>
+);
+```
+
+## Core Components
+
+### Box (Layout Foundation)
+
+The primary layout component. Use instead of View.
+
+```typescript
+import { Box } from "@terreno/ui";
+
+<Box
+  direction="row"
+  padding={4}
+  gap={2}
+  alignItems="center"
+  justifyContent="between"
+  backgroundColor="neutral100"
+>
+  <Text>Content</Text>
+</Box>
+```
+
+**Props:**
+- `direction`: "row" | "column" (default: "column")
+- `padding`, `paddingX`, `paddingY`: 0-12 (spacing scale)
+- `margin`, `marginX`, `marginY`: 0-12
+- `gap`: 0-12
+- `alignItems`: "start" | "center" | "end" | "stretch"
+- `justifyContent`: "start" | "center" | "end" | "between" | "around"
+- `flex`: number
+- `backgroundColor`: theme color key
+
+### Button
+
+```typescript
+import { Button } from "@terreno/ui";
+
+<Button
+  text="Submit"
+  onClick={handleSubmit}
+  variant="primary"
+  loading={isLoading}
+  disabled={!isValid}
+  fullWidth
+/>
+
+<Button
+  text="Delete"
+  variant="destructive"
+  withConfirmation
+  confirmationTitle="Delete Item?"
+  confirmationMessage="This cannot be undone."
+/>
+```
+
+**Variants:**
+- `primary` - Default filled button
+- `secondary` - Darker background
+- `outline` - Border only
+- `ghost` - Minimal, no background
+- `destructive` - Red/error color
+- `muted` - Light background
+
+### Text & Typography
+
+```typescript
+import { Text, Heading, Title } from "@terreno/ui";
+
+<Title>Page Title</Title>
+<Heading size="lg">Section Heading</Heading>
+<Text size="md" color="neutral600">Body text</Text>
+```
+
+### Form Fields
+
+```typescript
+import {
+  TextField,
+  EmailField,
+  PasswordField,
+  NumberField,
+  TextArea,
+  SelectField,
+  DateTimeField,
+  BooleanField,
+  CheckBox,
+  RadioField,
+} from "@terreno/ui";
+
+<TextField
+  label="Name"
+  value={name}
+  onChangeText={setName}
+  placeholder="Enter your name"
+  error={errors.name}
+  helperText="Your full legal name"
+/>
+
+<SelectField
+  label="Country"
+  value={country}
+  onChangeValue={setCountry}
+  options={[
+    { label: "United States", value: "US" },
+    { label: "Canada", value: "CA" },
+  ]}
+/>
+
+<DateTimeField
+  label="Date of Birth"
+  value={dob}
+  onChange={setDob}
+  mode="date"
+/>
+
+<BooleanField
+  label="Accept Terms"
+  value={accepted}
+  onChangeValue={setAccepted}
+/>
+```
+
+### Modal & Sheets
+
+```typescript
+import { Modal, ModalSheet, ActionSheet } from "@terreno/ui";
+
+<Modal
+  visible={showModal}
+  title="Confirm Action"
+  subtitle="Are you sure?"
+  primaryButtonText="Confirm"
+  secondaryButtonText="Cancel"
+  onPrimaryAction={handleConfirm}
+  onDismiss={() => setShowModal(false)}
+>
+  <Text>Modal content here</Text>
+</Modal>
+
+<ActionSheet
+  visible={showSheet}
+  title="Select Option"
+  onDismiss={() => setShowSheet(false)}
+>
+  <Button text="Option 1" onClick={handleOption1} />
+  <Button text="Option 2" onClick={handleOption2} />
+</ActionSheet>
+```
+
+### Table Components
+
+```typescript
+import {
+  Table,
+  TableHeader,
+  TableHeaderCell,
+  TableRow,
+  TableText,
+  TableDate,
+  TableBadge,
+} from "@terreno/ui";
+
+<Table data={users} keyExtractor={(item) => item.id}>
+  <TableHeader>
+    <TableHeaderCell>Name</TableHeaderCell>
+    <TableHeaderCell>Email</TableHeaderCell>
+    <TableHeaderCell>Status</TableHeaderCell>
+  </TableHeader>
+  {users.map((user) => (
+    <TableRow key={user.id} item={user}>
+      <TableText field="name" />
+      <TableText field="email" />
+      <TableBadge field="status" />
+    </TableRow>
+  ))}
+</Table>
+```
+
+### Page & Layout
+
+```typescript
+import { Page, SplitPage, ScrollView } from "@terreno/ui";
+
+<Page
+  navigation={navigation}
+  title="Dashboard"
+  headerRight={<IconButton name="settings" />}
+>
+  <ScrollView>
+    {/* Content */}
+  </ScrollView>
+</Page>
+```
+
+## Theme System
+
+### Using Theme
+
+```typescript
+import { useTheme } from "@terreno/ui";
+
+const MyComponent = () => {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <Box backgroundColor={theme.colors.primary500}>
+      <Text color={theme.colors.neutral100}>Themed content</Text>
+    </Box>
+  );
+};
+```
+
+### Theme Values
+
+**Colors:**
+- Primary: primary100-900
+- Secondary: secondary100-900
+- Accent: accent100-900
+- Neutral: neutral100-900
+- Error: error100-900
+- Success: success100-900
+- Warning: warning100-900
+
+**Spacing (0-12):**
+spacing0=0, spacing1=4, spacing2=8, spacing3=12, spacing4=16, spacing5=24, spacing6=32, spacing7=40, spacing8=48, spacing9=56, spacing10=64, spacing11=72, spacing12=80
+
+**Border Radius:**
+radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radius3xl
+
+## Utilities
+
+```typescript
+import { useStoredState, MediaQuery, isMobileDevice } from "@terreno/ui";
+
+// Persist state to storage
+const [value, setValue] = useStoredState("key", defaultValue);
+
+// Responsive rendering
+<MediaQuery minWidth={768}>
+  <DesktopLayout />
+</MediaQuery>
+
+// Device detection
+if (isMobileDevice()) {
+  // Mobile-specific code
+}
+```
+
+## Icons
+
+```typescript
+import { Icon, IconButton } from "@terreno/ui";
+
+<Icon name="check" size={24} color="success500" />
+<IconButton name="close" onClick={handleClose} />
+```
+
+## Best Practices
+
+1. Use `Box` as your primary layout component
+2. Use theme values instead of hardcoded colors/spacing
+3. Wrap callbacks with `useCallback`
+4. Use Luxon for dates (not Date or dayjs)
+5. Provide explicit return types on components
+6. Use `React.FC` for component typing

package/dist/docs/templates/bootstrap/CLAUDE.template.md

@@ -0,0 +1,41 @@
+# {{appDisplayName}}
+
+A full-stack application built with the Terreno framework.
+
+## Project Structure
+
+- **{{appName}}-frontend/** - Expo/React Native frontend
+- **{{appName}}-backend/** - Express/Mongoose backend
+
+## Development
+
+```bash
+# Install dependencies
+cd {{appName}}-backend && bun install
+cd {{appName}}-frontend && bun install
+
+# Start backend (port 4000)
+cd {{appName}}-backend && bun run dev
+
+# Start frontend (port 8082)
+cd {{appName}}-frontend && bun run web
+
+# Regenerate SDK after backend changes
+cd {{appName}}-frontend && bun run sdk
+```
+
+## Adding Features
+
+1. Create model in `{{appName}}-backend/src/models/`
+2. Create route in `{{appName}}-backend/src/api/`
+3. Register route in `{{appName}}-backend/src/server.ts`
+4. Regenerate SDK: `cd {{appName}}-frontend && bun run sdk`
+5. Create screens in `{{appName}}-frontend/app/`
+
+## Code Style
+
+- Use TypeScript with ES modules
+- Use Luxon for dates
+- Prefer const arrow functions
+- Named exports preferred
+- Use interfaces over types

package/dist/docs/templates/bootstrap/backend/api/users.template.md

@@ -0,0 +1,25 @@
+import {Permissions, type ModelRouterOptions, modelRouter} from "@terreno/api";
+import type {Router} from "express";
+import {User} from "../models";
+import type {UserDocument} from "../types";
+
+export const addUserRoutes = (
+  router: Router,
+  options?: Partial<ModelRouterOptions<UserDocument>>
+): void => {
+  router.use(
+    "/users",
+    modelRouter(User, {
+      ...options,
+      permissions: {
+        create: [Permissions.IsAdmin],
+        delete: [Permissions.IsAdmin],
+        list: [Permissions.IsAuthenticated],
+        read: [Permissions.IsAuthenticated],
+        update: [Permissions.IsAdmin],
+      },
+      queryFields: ["email", "name"],
+      sort: "name",
+    })
+  );
+};

package/dist/docs/templates/bootstrap/backend/index.template.md

@@ -0,0 +1 @@
+import "./server";

package/dist/docs/templates/bootstrap/backend/models/index.template.md

@@ -0,0 +1 @@
+export * from "./user";

package/dist/docs/templates/bootstrap/backend/models/modelPlugins.template.md

@@ -0,0 +1,15 @@
+import {
+  createdUpdatedPlugin,
+  findExactlyOne,
+  findOneOrNone,
+  isDeletedPlugin,
+} from "@terreno/api";
+import type mongoose from "mongoose";
+
+// biome-ignore lint/suspicious/noExplicitAny: Leaving open for flexibility
+export function addDefaultPlugins(schema: mongoose.Schema<any, any, any, any>): void {
+  schema.plugin(createdUpdatedPlugin);
+  schema.plugin(isDeletedPlugin);
+  schema.plugin(findOneOrNone);
+  schema.plugin(findExactlyOne);
+}

package/dist/docs/templates/bootstrap/backend/models/user.template.md

@@ -0,0 +1,42 @@
+import mongoose from "mongoose";
+import passportLocalMongoose from "passport-local-mongoose";
+import type {UserDocument, UserModel} from "../types";
+import {addDefaultPlugins} from "./modelPlugins";
+
+const userSchema = new mongoose.Schema<UserDocument, UserModel>(
+  {
+    admin: {
+      default: false,
+      type: Boolean,
+    },
+    email: {
+      lowercase: true,
+      required: true,
+      trim: true,
+      type: String,
+      unique: true,
+    },
+    name: {
+      required: true,
+      trim: true,
+      type: String,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+userSchema.plugin(passportLocalMongoose, {
+  usernameField: "email",
+});
+
+addDefaultPlugins(userSchema);
+
+userSchema.method("getDisplayName", function (this: UserDocument): string {
+  return this.name;
+});
+
+export const User = mongoose.model<UserDocument, UserModel>("User", userSchema);
+
+User.findByEmail = async function (email: string): Promise<UserDocument | null> {
+  return this.findOneOrNone({email: email.toLowerCase()});
+};

package/dist/docs/templates/bootstrap/backend/server.template.md

@@ -0,0 +1,44 @@
+import {type AddRoutes, checkModelsStrict, logger, setupServer} from "@terreno/api";
+import {addUserRoutes} from "./api/users";
+import {User} from "./models/user";
+import {connectToMongoDB} from "./utils/database";
+
+const isDeployed = process.env.NODE_ENV === "production";
+
+const addMiddleware: AddRoutes = (_router, _options) => {
+  // Add middleware here
+};
+
+const addRoutes: AddRoutes = (router, options): void => {
+  // Add API routes
+  addUserRoutes(router, options);
+};
+
+export async function start(skipListen = false): Promise<ReturnType<typeof setupServer>> {
+  await connectToMongoDB();
+
+  logger.info(`Starting {{appDisplayName}} server on port ${process.env.PORT || 4000}`);
+
+  if (!isDeployed) {
+    checkModelsStrict();
+  }
+
+  const app = setupServer({
+    addMiddleware,
+    addRoutes,
+    loggingOptions: {
+      disableConsoleColors: isDeployed,
+      level: "debug",
+      logRequests: !isDeployed,
+    },
+    skipListen,
+    // biome-ignore lint/suspicious/noExplicitAny: Typing User model
+    userModel: User as any,
+  });
+
+  return app;
+}
+
+start().catch((error) => {
+  logger.error(`Fatal error starting server: ${error}`);
+});

package/dist/docs/templates/bootstrap/backend/types/index.template.md

@@ -0,0 +1 @@
+export * from "./models";

package/dist/docs/templates/bootstrap/backend/types/models/index.template.md

@@ -0,0 +1 @@
+export * from "./userTypes";

package/dist/docs/templates/bootstrap/backend/types/models/userTypes.template.md

@@ -0,0 +1,47 @@
+/// <reference types="passport-local-mongoose" />
+import type {APIErrorConstructor} from "@terreno/api";
+import type mongoose from "mongoose";
+import type {Document, FilterQuery, Model} from "mongoose";
+
+export interface DefaultStatics<T> {
+  findOneOrNone(
+    query: FilterQuery<T>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<(Document & T) | null>;
+
+  findExactlyOne(
+    query: FilterQuery<T>,
+    errorArgs?: Partial<APIErrorConstructor>
+  ): Promise<Document & T>;
+}
+
+export interface DefaultPluginFields {
+  created: Date;
+  updated: Date;
+  deleted: boolean;
+}
+
+export type DefaultModel<T> = Model<T & DefaultPluginFields> & DefaultStatics<T>;
+export type DefaultDoc = mongoose.Document<mongoose.Types.ObjectId> & DefaultPluginFields;
+
+export type UserMethods = {
+  getDisplayName: (this: UserDocument) => string;
+};
+
+export type UserStatics = DefaultStatics<UserDocument> & {
+  findByEmail: (this: UserModel, email: string) => Promise<UserDocument | null>;
+};
+
+export type UserModel = DefaultModel<UserDocument> &
+  UserStatics &
+  mongoose.PassportLocalModel<UserDocument>;
+
+export type UserSchema = mongoose.Schema<UserDocument, UserModel, UserMethods>;
+
+export type UserDocument = DefaultDoc &
+  UserMethods &
+  mongoose.PassportLocalDocument & {
+    admin: boolean;
+    email: string;
+    name: string;
+  };

package/dist/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/dist/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/dist/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/dist/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;