@terreno/mcp 0.21.0

package/src/docs/prompts/form.md

@@ -0,0 +1,85 @@
+# Form Generation
+
+Create a form component with the following specifications:
+
+## Form Details
+- **Name**: {{name}}Form
+- **Purpose**: {{purpose}}
+
+## Fields
+{{fieldsList}}
+
+## Implementation Requirements
+
+### Component Structure
+```tsx
+import {Box, Button, TextField, SelectField} from "@terreno/ui";
+import type React from "react";
+import {useCallback, useState} from "react";
+
+interface {{Name}}FormProps {
+  initialValues?: Partial<{{Name}}FormValues>;
+  onSubmit: (values: {{Name}}FormValues) => Promise<void>;
+  isLoading?: boolean;
+}
+
+interface {{Name}}FormValues {
+  {{fieldsInterface}}
+}
+
+export const {{Name}}Form: React.FC<{{Name}}FormProps> = ({
+  initialValues,
+  onSubmit,
+  isLoading,
+}) => {
+  {{stateDeclarations}}
+  {{errorStates}}
+
+  const validate = useCallback((): boolean => {
+    let isValid = true;
+    {{validationLogic}}
+    return isValid;
+  }, [{{dependencies}}]);
+
+  const handleSubmit = useCallback(async (): Promise<void> => {
+    if (!validate()) {
+      return;
+    }
+    await onSubmit({
+      {{submitValues}}
+    });
+  }, [{{submitDependencies}}]);
+
+  return (
+    <Box gap={4}>
+      {{formFields}}
+      <Button
+        text="Submit"
+        onClick={handleSubmit}
+        loading={isLoading}
+        disabled={isLoading}
+        fullWidth
+      />
+    </Box>
+  );
+};
+```
+
+### Validation
+- Validate required fields
+- Show inline error messages
+- Disable submit while loading
+
+### Field Types
+- **text**: Use `TextField`
+- **email**: Use `TextField` with `type="email"`
+- **password**: Use `TextField` with `type="password"`
+- **number**: Use `TextField` with `type="number"`
+- **select**: Use `SelectField` with options
+- **date**: Use `DateTimeField`
+- **checkbox**: Use `CheckBox`
+
+### Integration
+- Import and use in screen components
+- Pass mutation function as `onSubmit`
+- Handle success/error states in parent

package/src/docs/prompts/migrate-to-terreno-app.md

@@ -0,0 +1,290 @@
+# Migration Guide: setupServer to TerrenoApp
+
+You are helping a user migrate their Express backend from the legacy `setupServer` function to the new `TerrenoApp` builder API in `@terreno/api`.
+
+## Overview
+
+`setupServer` is being replaced by `TerrenoApp`, a fluent builder API that provides:
+- Explicit configuration (no environment variables)
+- Plugin system via `TerrenoPlugin` interface
+- Lifecycle hooks at every initialization stage
+- Fluent `.addModelRouter()`, `.addRoute()`, `.addMiddleware()` methods
+- Built-in graceful shutdown
+
+## Step-by-Step Migration
+
+### 1. Replace setupServer with TerrenoApp.create
+
+**Before:**
+```typescript
+import {setupServer, setupEnvironment} from "@terreno/api";
+
+setupEnvironment(); // validates env vars
+
+const app = setupServer({
+  userModel: User,
+  addRoutes,
+  addMiddleware,
+  skipListen,
+  corsOrigin: "*",
+  loggingOptions: { ... },
+  authOptions: { ... },
+});
+```
+
+**After:**
+```typescript
+import {TerrenoApp} from "@terreno/api";
+
+const terrenoApp = TerrenoApp.create({
+  auth: {
+    userModel: User,
+    token: {
+      issuer: process.env.TOKEN_ISSUER!,
+      secret: process.env.TOKEN_SECRET!,
+      expiresIn: process.env.TOKEN_EXPIRES_IN ?? "1h",
+    },
+    refreshToken: {
+      secret: process.env.REFRESH_TOKEN_SECRET!,
+    },
+    session: {
+      secret: process.env.SESSION_SECRET!,
+    },
+  },
+  server: {
+    port: Number(process.env.PORT) || 9000,
+    skipListen,
+  },
+  middleware: {
+    cors: {
+      origin: "*",
+    },
+  },
+  logging: {
+    requests: {
+      enabled: true,
+    },
+  },
+});
+
+await terrenoApp.start();
+```
+
+### 2. Move addRoutes to fluent .addModelRouter() and .addRoute() calls
+
+**Before:**
+```typescript
+const addRoutes: AddRoutes = (router, options) => {
+  router.use("/todos", modelRouter(Todo, {
+    ...options,
+    permissions: { ... },
+    queryFields: ["completed", "ownerId"],
+    sort: "-created",
+  }));
+  router.use("/custom", customRouter);
+};
+```
+
+**After:**
+```typescript
+TerrenoApp.create({ ... })
+  .addModelRouter("/todos", Todo, {
+    permissions: {
+      create: [Permissions.IsAuthenticated],
+      read: [Permissions.IsOwner],
+      update: [Permissions.IsOwner],
+      delete: [Permissions.IsOwner],
+      list: [Permissions.IsAuthenticated],
+    },
+    queryFields: ["completed", "ownerId"],
+    sort: "-created",
+  })
+  .addRoute("/custom", customRouter)
+  .start();
+```
+
+### 3. Move addMiddleware to fluent .addMiddleware() calls
+
+**Before:**
+```typescript
+const addMiddleware: AddRoutes = (router) => {
+  router.use(myCustomMiddleware);
+};
+```
+
+**After:**
+```typescript
+TerrenoApp.create({ ... })
+  .addMiddleware(myCustomMiddleware)
+  .start();
+```
+
+### 4. Replace health options with HealthApp plugin
+
+The health endpoint is now a separate package `@terreno/api-health` that uses the `TerrenoPlugin` interface.
+
+**Install:**
+Add `@terreno/api-health` to your package.json dependencies.
+
+**Before (if using inline health):**
+```typescript
+const app = setupServer({ ... });
+// No built-in health in setupServer
+```
+
+**After:**
+```typescript
+import {HealthApp} from "@terreno/api-health";
+
+TerrenoApp.create({ ... })
+  .use(new HealthApp({
+    check: async () => {
+      const dbConnected = mongoose.connection.readyState === 1;
+      return {
+        healthy: dbConnected,
+        details: {
+          database: dbConnected ? "connected" : "disconnected",
+          uptime: process.uptime(),
+        },
+      };
+    },
+  }))
+  .start();
+```
+
+**Or standalone (without TerrenoApp):**
+```typescript
+import {HealthApp} from "@terreno/api-health";
+
+const app = setupServer({ ... });
+new HealthApp({ check: async () => ({ healthy: true }) }).register(app);
+```
+
+### 5. Replace environment variable checks with explicit config
+
+**Before (implicit env vars):**
+```
+TOKEN_ISSUER=my-app
+TOKEN_SECRET=secret123
+REFRESH_TOKEN_SECRET=refresh123
+SESSION_SECRET=session123
+TOKEN_EXPIRES_IN=1h
+```
+
+**After (explicit in code):**
+```typescript
+TerrenoApp.create({
+  auth: {
+    userModel: User,
+    token: {
+      issuer: "my-app",
+      secret: process.env.TOKEN_SECRET!,
+      expiresIn: "1h",
+    },
+    refreshToken: {
+      secret: process.env.REFRESH_TOKEN_SECRET!,
+    },
+    session: {
+      secret: process.env.SESSION_SECRET!,
+    },
+  },
+});
+```
+
+### 6. Use hooks for lifecycle customization
+
+**Before (scattered setup):**
+```typescript
+const app = setupServer({ ... });
+// Manual setup after server creation
+app.use("/admin", adminMiddleware);
+```
+
+**After (structured hooks):**
+```typescript
+TerrenoApp.create({
+  hooks: {
+    onAuthReady: (app) => {
+      app.use("/admin", adminMiddleware);
+    },
+    onListening: (server, port) => {
+      logger.info(`Server listening on port ${port}`);
+    },
+    onError: (error, req) => {
+      errorTracker.capture(error, { url: req.url });
+    },
+  },
+});
+```
+
+### 7. Add graceful shutdown
+
+**Before (manual or none):**
+```typescript
+process.on("SIGTERM", () => {
+  mongoose.disconnect();
+  process.exit(0);
+});
+```
+
+**After:**
+```typescript
+TerrenoApp.create({
+  shutdown: {
+    handleSignals: true,
+    timeout: 30000,
+    onShutdown: async () => {
+      await mongoose.disconnect();
+    },
+  },
+});
+```
+
+## Plugin System
+
+The `TerrenoPlugin` interface allows modular composition:
+
+```typescript
+import type {TerrenoPlugin} from "@terreno/api";
+import type express from "express";
+
+export class MyPlugin implements TerrenoPlugin {
+  register(app: express.Application): void {
+    // Register routes, middleware, etc.
+    app.get("/my-endpoint", (req, res) => {
+      res.json({ok: true});
+    });
+  }
+}
+```
+
+Available plugins:
+- `@terreno/api-health` - Health check endpoint (`HealthApp`)
+
+## Key Differences
+
+| Feature | setupServer | TerrenoApp |
+|---------|------------|------------|
+| Configuration | env vars + options | Explicit options only |
+| Routes | `addRoutes` callback | Fluent `.addModelRouter()` / `.addRoute()` |
+| Middleware | `addMiddleware` callback | Fluent `.addMiddleware()` |
+| Health | None built-in | Plugin: `@terreno/api-health` |
+| Hooks | None | Full lifecycle hooks |
+| Shutdown | Manual | Built-in graceful shutdown |
+| Plugins | None | `TerrenoPlugin` interface |
+
+## Migration Checklist
+
+When migrating a file, verify:
+
+- [ ] `setupServer` replaced with `TerrenoApp.create().start()`
+- [ ] `setupEnvironment()` call removed (no longer needed)
+- [ ] Auth tokens configured explicitly in `auth` option
+- [ ] `addRoutes` callback replaced with `.addModelRouter()` / `.addRoute()` calls
+- [ ] `addMiddleware` callback replaced with `.addMiddleware()` calls
+- [ ] CORS configured in `middleware.cors` option
+- [ ] Logging configured in `logging` option
+- [ ] Health endpoint added via `@terreno/api-health` if needed
+- [ ] Graceful shutdown configured in `shutdown` option
+- [ ] `skipListen` moved to `server.skipListen`
+- [ ] Tests updated to use `TerrenoApp.create({ server: { skipListen: true } }).build()`

package/src/docs/prompts/screen.md

@@ -0,0 +1,72 @@
+# Screen Generation
+
+Create a new screen with the following specifications:
+
+## Screen Details
+- **Name**: {{name}}
+- **Type**: {{type}}
+- **Route**: {{route}}
+
+## Features
+{{featuresList}}
+
+## Implementation Requirements
+
+### File Structure
+- Create screen at `app/{{route}}.tsx`
+- Add any shared components to `components/`
+
+### Required Elements
+1. Use `Page` component as wrapper
+2. Include proper navigation title
+3. Handle loading states with `Spinner`
+4. Handle error states with appropriate messaging
+5. Use @terreno/ui components throughout
+
+### Data Fetching
+{{dataSection}}
+
+### Example Structure
+```tsx
+import {Box, Page, Text, Spinner} from "@terreno/ui";
+import type React from "react";
+import {useGet{{Model}}Query} from "@/store";
+
+const {{Name}}Screen: React.FC = () => {
+  const {data, isLoading, error} = useGet{{Model}}Query();
+
+  if (isLoading) {
+    return (
+      <Page navigation={undefined} title="{{title}}">
+        <Box padding={4} alignItems="center">
+          <Spinner />
+        </Box>
+      </Page>
+    );
+  }
+
+  if (error) {
+    return (
+      <Page navigation={undefined} title="{{title}}">
+        <Box padding={4}>
+          <Text color="error">Failed to load data</Text>
+        </Box>
+      </Page>
+    );
+  }
+
+  return (
+    <Page navigation={undefined} title="{{title}}">
+      <Box padding={4} gap={4}>
+        {/* Screen content */}
+      </Box>
+    </Page>
+  );
+};
+
+export default {{Name}}Screen;
+```
+
+### Navigation
+- Add to tab layout if needed in `app/(tabs)/_layout.tsx`
+- Or add as stack screen in appropriate layout

package/src/docs/prompts/style-guide.md

@@ -0,0 +1,162 @@
+# Terreno Code Style Guide
+
+## TypeScript/JavaScript
+
+### General
+- 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`, `hasError`)
+- Use camelCase directories (e.g., `components/authWizard`)
+- Favor named exports over default exports
+- Use the RORO pattern (Receive an Object, Return an Object)
+
+### Functions
+```typescript
+// Good
+const processUser = ({ id, name }: ProcessUserArgs): ProcessUserResult => {
+  // ...
+};
+
+// Avoid
+function processUser(id: string, name: string) {
+  // ...
+}
+```
+
+### Dates and Time
+- Always use Luxon instead of Date or dayjs
+```typescript
+import { DateTime } from "luxon";
+
+const now = DateTime.now();
+const formatted = now.toFormat("yyyy-MM-dd");
+```
+
+### 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
+
+```typescript
+// Good
+const validateUser = (user: User): ValidationResult => {
+  if (!user.email) {
+    return { valid: false, error: "Email required" };
+  }
+
+  if (!user.name) {
+    return { valid: false, error: "Name required" };
+  }
+
+  return { valid: true };
+};
+
+// Avoid
+const validateUser = (user: User) => {
+  if (user.email) {
+    if (user.name) {
+      return { valid: true };
+    } else {
+      return { valid: false, error: "Name required" };
+    }
+  } else {
+    return { valid: false, error: "Email required" };
+  }
+};
+```
+
+## React Components
+
+### Component Structure
+```typescript
+import React, { useCallback, useState } from "react";
+import { Box, Text } from "@terreno/ui";
+
+interface MyComponentProps {
+  title: string;
+  onPress?: () => void;
+}
+
+export const MyComponent: React.FC<MyComponentProps> = ({ title, onPress }) => {
+  const [isActive, setIsActive] = useState(false);
+
+  const handlePress = useCallback(() => {
+    setIsActive(true);
+    onPress?.();
+  }, [onPress]);
+
+  return (
+    <Box padding={4}>
+      <Text>{title}</Text>
+    </Box>
+  );
+};
+```
+
+### Hooks
+- Direct hook imports: `import { useEffect, useMemo } from 'react'`
+- Wrap callbacks with `useCallback`
+- Use `useMemo` for expensive computations
+- Always provide explicit return types
+
+## Logging
+
+### Frontend
+```typescript
+// Permanent logs
+console.info("User logged in", { userId });
+console.debug("Fetching data", { params });
+console.warn("Deprecated feature used");
+console.error("Failed to load", { error });
+
+// Debugging only (remove before commit)
+console.log("temporary debug");
+```
+
+### Backend
+```typescript
+import { logger } from "@terreno/api";
+
+logger.info("Request received", { path, method });
+logger.debug("Processing data", { data });
+logger.warn("Rate limit approaching", { remaining });
+logger.error("Database error", { error });
+```
+
+## Testing
+
+- Use bun test with expect
+- Never mock @terreno/api or models
+- Use manual mocks in `__mocks__/` directory
+
+```typescript
+import { expect, test, describe } from "bun:test";
+
+describe("MyFeature", () => {
+  test("should do something", () => {
+    const result = myFunction();
+    expect(result).toBe(expected);
+  });
+});
+```
+
+## Comments
+
+- Comments should describe purpose, not effect
+- Don't add comments to obvious code
+- Use JSDoc for public APIs
+
+```typescript
+// Good - explains why
+// Skip validation for admin users to allow bulk imports
+if (user.admin) {
+  return true;
+}
+
+// Avoid - describes what (obvious from code)
+// Check if user is admin
+if (user.admin) {
+  return true;
+}
+```