@terreno/mcp 0.21.0

package/src/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

package/src/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/src/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/src/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/src/docs/templates/bootstrap/backend/index.template.md

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

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

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

package/src/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/src/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/src/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/src/docs/templates/bootstrap/backend/types/index.template.md

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

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

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

package/src/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;
+  };