@terreno/mcp 0.22.2 → 0.23.1

package/dist/docs/versioned/0.23.0/how-to/configure-better-auth.md

@@ -0,0 +1,296 @@
+# Configure Better Auth
+
+Set up Better Auth as an alternative authentication provider with built-in social OAuth support.
+
+## Overview
+
+Better Auth is an optional authentication system that runs **alongside** the existing JWT/Passport authentication. You can choose which authentication provider to use at server startup via environment variables.
+
+**Use Better Auth when you need:**
+- Social login (Google, GitHub, Apple)
+- Session-based authentication
+- Modern OAuth 2.0 flows
+
+**Use JWT authentication when you need:**
+- Stateless authentication
+- Simpler token-based auth
+- No social login required
+
+## Backend Setup
+
+### 1. Configure Environment Variables
+
+Set `AUTH_PROVIDER` to enable Better Auth:
+
+``````bash
+# Choose authentication provider
+AUTH_PROVIDER=better-auth  # or "jwt" (default)
+
+# Better Auth configuration
+BETTER_AUTH_SECRET=your-secret-key-min-32-chars
+BETTER_AUTH_URL=http://localhost:4000
+
+# Optional: Social OAuth providers
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+GITHUB_CLIENT_ID=your-github-client-id  
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+APPLE_CLIENT_ID=your-apple-client-id
+APPLE_CLIENT_SECRET=your-apple-client-secret
+``````
+
+### 2. Build Better Auth Configuration
+
+Create a function to build your Better Auth config:
+
+``````typescript
+import {BetterAuthConfig, AuthProvider} from "@terreno/api";
+
+const buildBetterAuthConfig = (): BetterAuthConfig | undefined => {
+  const authProvider = process.env.AUTH_PROVIDER as AuthProvider | undefined;
+
+  if (authProvider !== "better-auth") {
+    return undefined; // Use JWT auth instead
+  }
+
+  const config: BetterAuthConfig = {
+    enabled: true,
+    // Deep link schemes for mobile app redirects
+    trustedOrigins: ["yourapp://", "exp://"],
+  };
+
+  // Add Google OAuth if configured
+  if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+    config.googleOAuth = {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    };
+  }
+
+  // Add GitHub OAuth if configured
+  if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+    config.githubOAuth = {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    };
+  }
+
+  // Add Apple OAuth if configured
+  if (process.env.APPLE_CLIENT_ID && process.env.APPLE_CLIENT_SECRET) {
+    config.appleOAuth = {
+      clientId: process.env.APPLE_CLIENT_ID,
+      clientSecret: process.env.APPLE_CLIENT_SECRET,
+    };
+  }
+
+  return config;
+};
+``````
+
+### 3. Register BetterAuthApp Plugin
+
+Use the TerrenoApp plugin system:
+
+``````typescript
+import {TerrenoApp, BetterAuthApp} from "@terreno/api";
+import {User} from "./models/user";
+
+const betterAuthConfig = buildBetterAuthConfig();
+
+const app = new TerrenoApp({
+  userModel: User,
+  // ... other options
+});
+
+// Register Better Auth plugin if configured
+if (betterAuthConfig) {
+  app.register(new BetterAuthApp({
+    config: betterAuthConfig,
+    userModel: User,
+  }));
+}
+
+const server = app.start();
+``````
+
+### 4. Update User Model
+
+Add optional Better Auth fields to your User schema:
+
+``````typescript
+import {betterAuthUserPlugin} from "@terreno/api";
+
+const userSchema = new mongoose.Schema({
+  email: {type: String, unique: true},
+  name: {type: String},
+  // ... other fields
+});
+
+// Adds: betterAuthId, oauthProvider
+userSchema.plugin(betterAuthUserPlugin);
+``````
+
+## Frontend Setup
+
+### 1. Create Better Auth Client
+
+``````typescript
+import {createBetterAuthClient} from "@terreno/rtk";
+
+export const authClient = createBetterAuthClient({
+  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+});
+``````
+
+### 2. Add Session Redux Slice
+
+``````typescript
+import {generateBetterAuthSlice} from "@terreno/rtk";
+import {configureStore} from "@reduxjs/toolkit";
+import {authClient} from "./authClient";
+
+const {sessionReducer, sessionMiddleware} = generateBetterAuthSlice(authClient);
+
+export const store = configureStore({
+  reducer: {
+    session: sessionReducer,
+    // ... other reducers
+  },
+  middleware: (getDefault) => getDefault().concat(sessionMiddleware),
+});
+``````
+
+### 3. Add Social Login UI
+
+Use the SocialLoginButton component:
+
+``````typescript
+import {SocialLoginButton, Box} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+const LoginScreen = () => {
+  return (
+    <Box padding={4} gap={3}>
+      <SocialLoginButton
+        provider="google"
+        onPress={async () => {
+          await authClient.signIn.social({
+            provider: "google",
+            callbackURL: "yourapp://auth/callback",
+          });
+        }}
+      />
+      
+      <SocialLoginButton
+        provider="github"
+        onPress={async () => {
+          await authClient.signIn.social({
+            provider: "github",
+            callbackURL: "yourapp://auth/callback",
+          });
+        }}
+      />
+      
+      <SocialLoginButton
+        provider="apple"
+        onPress={async () => {
+          await authClient.signIn.social({
+            provider: "apple",
+            callbackURL: "yourapp://auth/callback",
+          });
+        }}
+      />
+    </Box>
+  );
+};
+``````
+
+## OAuth Provider Setup
+
+### Google OAuth
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Enable Google+ API
+4. Create OAuth 2.0 credentials
+5. Add authorized redirect URIs:
+   - `http://localhost:4000/api/auth/callback/google` (development)
+   - `https://yourapp.com/api/auth/callback/google` (production)
+6. Copy Client ID and Client Secret to `.env`
+
+### GitHub OAuth
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Create a new OAuth App
+3. Set Authorization callback URL:
+   - `http://localhost:4000/api/auth/callback/github` (development)
+   - `https://yourapp.com/api/auth/callback/github` (production)
+4. Copy Client ID and generate Client Secret
+5. Add to `.env`
+
+### Apple Sign In
+
+1. Go to [Apple Developer Console](https://developer.apple.com/)
+2. Create a new Services ID
+3. Configure Sign in with Apple
+4. Add return URLs (similar to above)
+5. Generate private key and download
+6. Copy Service ID and Key to `.env`
+
+## Generated Endpoints
+
+When Better Auth is enabled, these endpoints are available:
+
+- `POST /api/auth/signup/email` — Email/password signup
+- `POST /api/auth/signin/email` — Email/password signin
+- `GET /api/auth/signin/google` — Initiate Google OAuth
+- `GET /api/auth/signin/github` — Initiate GitHub OAuth
+- `GET /api/auth/signin/apple` — Initiate Apple Sign In
+- `GET /api/auth/callback/{provider}` — OAuth callback handler
+- `POST /api/auth/signout` — Sign out current session
+- `GET /api/auth/session` — Get current session
+
+## Troubleshooting
+
+### "BETTER_AUTH_SECRET is not set"
+
+Ensure you've set both `AUTH_PROVIDER=better-auth` and `BETTER_AUTH_SECRET` in your environment variables.
+
+### OAuth redirect mismatch
+
+Verify the callback URLs in your OAuth provider settings match your `BETTER_AUTH_URL` + `/api/auth/callback/{provider}`.
+
+### Session not persisting
+
+Check that `trustedOrigins` in your Better Auth config includes your app's deep link scheme (e.g., `"yourapp://"`).
+
+### Social login opens browser but doesn't redirect back
+
+Ensure your mobile app has the proper deep link configuration in `app.json`:
+
+``````json
+{
+  "expo": {
+    "scheme": "yourapp"
+  }
+}
+``````
+
+## Migration from JWT Auth
+
+Better Auth runs **in parallel** with JWT auth. You don't need to migrate existing users immediately:
+
+1. Set `AUTH_PROVIDER=better-auth`
+2. Keep existing JWT endpoints available (they still work)
+3. New users can sign up via Better Auth
+4. Existing users continue using JWT tokens
+5. Optionally add migration logic to link accounts
+
+## Learn More
+
+- [Authentication Architecture](../explanation/authentication.md)
+- [@terreno/api Reference](../reference/api.md#better-auth)
+- [@terreno/rtk Reference](../reference/rtk.md#better-auth)
+- [Better Auth Documentation](https://better-auth.com/)

package/dist/docs/versioned/0.23.0/how-to/create-a-model.md

@@ -0,0 +1,165 @@
+# How to Create a Mongoose Model
+
+Learn how to create a Mongoose model with Terreno conventions for use with modelRouter.
+
+## Prerequisites
+
+- Basic understanding of MongoDB and Mongoose
+- @terreno/api installed
+- MongoDB connection configured
+
+## Step-by-step
+
+### 1. Define TypeScript interfaces
+
+Create type definitions for your model document, model statics, and methods:
+
+``````typescript
+// src/types/models/todoTypes.ts
+import type mongoose from "mongoose";
+import type {DefaultDoc, DefaultModel} from "@terreno/api";
+
+export interface TodoDocument extends DefaultDoc {
+  title: string;
+  completed: boolean;
+  ownerId: mongoose.Types.ObjectId;
+}
+
+export interface TodoModel extends DefaultModel<TodoDocument> {
+  // Add custom static methods here if needed
+}
+``````
+
+### 2. Create the schema with field descriptions
+
+**Important:** Every field **must** include a `description` property. This flows through to the OpenAPI spec and makes generated SDK documentation more useful.
+
+``````typescript
+// src/models/todo.ts
+import mongoose from "mongoose";
+import type {TodoDocument, TodoModel} from "../types";
+import {addDefaultPlugins} from "./modelPlugins";
+
+const todoSchema = new mongoose.Schema<TodoDocument, TodoModel>(
+  {
+    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},
+  }
+);
+``````
+
+### 3. Add plugins
+
+Apply default plugins to get standard fields (created, updated, deleted):
+
+``````typescript
+addDefaultPlugins(todoSchema);
+``````
+
+The default plugins typically include:
+- `createdUpdatedPlugin` — Adds `created` and `updated` timestamps
+- `isDeletedPlugin` — Adds soft delete support with `deleted` field
+- `findExactlyOne` and `findOneOrNone` — Safe query methods
+
+### 4. Export the model
+
+``````typescript
+export const Todo = mongoose.model<TodoDocument, TodoModel>("Todo", todoSchema);
+``````
+
+### 5. Create routes with modelRouter
+
+Use the model with `modelRouter` to generate CRUD endpoints:
+
+``````typescript
+// src/api/todos.ts
+import {Router} from "express";
+import {modelRouter, Permissions, OwnerQueryFilter} from "@terreno/api";
+import {Todo} from "../models/todo";
+
+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],
+      },
+      preCreate: (body, req) => ({
+        ...body,
+        ownerId: req.user?._id,
+      }),
+      queryFilter: OwnerQueryFilter,
+      queryFields: ["completed", "ownerId"],
+      sort: "-created",
+    })
+  );
+};
+``````
+
+## Field description guidelines
+
+When writing field descriptions:
+
+- **Be concise:** One clear sentence is usually enough
+- **Explain purpose, not type:** The type is already specified
+- **Use active voice:** "The user who owns..." not "The owner of..."
+- **Include constraints if relevant:** "Email address (must be unique)"
+
+### Good examples
+
+``````typescript
+{
+  email: {
+    description: "User's email address (must be unique)",
+    type: String,
+    required: true,
+    unique: true,
+  },
+  createdAt: {
+    description: "Timestamp when the record was created",
+    type: Date,
+    default: Date.now,
+  },
+  status: {
+    description: "Current status of the order",
+    type: String,
+    enum: ["pending", "processing", "completed"],
+  },
+}
+``````
+
+## Next steps
+
+- Learn about [modelRouter options](../reference/api.md)
+- Explore [permissions and access control](../reference/api.md#permissions)
+- See the [example-backend](../../example-backend/) for a complete working example
+
+## See also
+
+- [@terreno/api reference](../reference/api.md)
+- [Getting started tutorial](../tutorials/getting-started.md)
+- [example-backend source](../../example-backend/src/models/)

package/dist/docs/versioned/0.23.0/how-to/deploy-to-gcp.md

@@ -0,0 +1,244 @@
+# Deploy to Google Cloud Platform
+
+Learn how to deploy the Terreno demo and example-frontend apps to Google Cloud Storage with CDN-backed hosting.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **GCP Project**: A Google Cloud Platform project with billing enabled
+- **gcloud CLI**: [Installed and authenticated](https://cloud.google.com/sdk/docs/install)
+- **Permissions**: Your GCP user or service account needs:
+  - `roles/storage.admin` (create buckets, set IAM)
+  - `roles/compute.loadBalancerAdmin` (create backend buckets, URL maps)
+  - `roles/compute.networkAdmin` (create IPs, proxies, forwarding rules)
+- **GitHub Repository Access**: Admin access to configure secrets
+
+## Initial Infrastructure Setup
+
+Run the setup script once to provision all GCP resources:
+
+``````bash
+# Clone the repository
+git clone https://github.com/FlourishHealth/terreno.git
+cd terreno
+
+# Run the setup script
+./scripts/setup-gcs-hosting.sh
+``````
+
+The script will prompt you for your service account email if `GCP_SA_KEY` is not set. It will create:
+
+1. **GCS Buckets**: `flourish-terreno-terreno-demo` and `flourish-terreno-terreno-frontend-example`
+2. **Public Access**: Configured with `allUsers:objectViewer`
+3. **SPA Routing**: `notFoundPage=index.html` for client-side routing
+4. **CDN Resources**:
+   - Backend buckets (CDN-enabled)
+   - URL maps
+   - Static IP addresses
+   - HTTP proxies
+   - Forwarding rules
+
+### Script Output
+
+At the end, the script outputs:
+
+``````
+=== Setup Complete ===
+
+Demo:
+  CDN IP: 34.120.xxx.xxx
+  URL: http://34.120.xxx.xxx/
+  (Point your DNS A record to this IP)
+
+Frontend Example:
+  CDN IP: 34.149.xxx.xxx
+  URL: http://34.149.xxx.xxx/
+  (Point your DNS A record to this IP)
+``````
+
+## Configure GitHub Secrets
+
+Add the following secret to your GitHub repository:
+
+### GCP_SA_KEY
+
+1. Create a service account key:
+   ``````bash
+   # Create service account
+   gcloud iam service-accounts create terreno-deploy \
+     --display-name="Terreno Deploy"
+
+   # Grant permissions
+   gcloud projects add-iam-policy-binding flourish-terreno \
+     --member="serviceAccount:terreno-deploy@flourish-terreno.iam.gserviceaccount.com" \
+     --role="roles/storage.objectAdmin"
+
+   gcloud projects add-iam-policy-binding flourish-terreno \
+     --member="serviceAccount:terreno-deploy@flourish-terreno.iam.gserviceaccount.com" \
+     --role="roles/compute.loadBalancerAdmin"
+
+   # Create JSON key
+   gcloud iam service-accounts keys create key.json \
+     --iam-account=terreno-deploy@flourish-terreno.iam.gserviceaccount.com
+   ``````
+
+2. Add the key to GitHub:
+   - Go to **Settings** → **Secrets and variables** → **Actions**
+   - Click **New repository secret**
+   - Name: `GCP_SA_KEY`
+   - Value: Paste the entire contents of `key.json`
+   - Click **Add secret**
+
+3. Delete the local key file:
+   ``````bash
+   rm key.json
+   ``````
+
+## Deploy to Production
+
+Production deployments happen automatically when you push to the `master` branch:
+
+``````bash
+# Make changes to demo or example-frontend
+git checkout master
+git pull
+# ... make changes ...
+git add .
+git commit -m "Update demo UI"
+git push origin master
+``````
+
+The workflows will:
+1. Build the app with Bun and Expo
+2. Upload the build artifact
+3. Sync assets to GCS with cache headers:
+   - Hashed assets: `Cache-Control: public, max-age=31536000, immutable`
+   - `index.html`: `Cache-Control: no-cache, no-store, must-revalidate`
+4. Invalidate the CDN cache
+
+### Triggered Workflows
+
+| App | Workflow | Triggers on paths |
+|-----|----------|-------------------|
+| Demo | `demo-deploy.yml` | `demo/**`, `ui/**` |
+| Example Frontend | `frontend-example-deploy.yml` | `example-frontend/**`, `ui/**`, `rtk/**` |
+
+## Deploy PR Previews
+
+Pull request previews deploy automatically when you open a PR that modifies the relevant paths:
+
+``````bash
+# Create a feature branch
+git checkout -b feature/new-component
+
+# Make changes
+# ... edit files ...
+
+git add .
+git commit -m "Add new component"
+git push origin feature/new-component
+
+# Open a pull request on GitHub
+``````
+
+The workflow will:
+1. Build the app with a preview-specific `baseUrl`
+2. Deploy to `gs://BUCKET/_previews/pr-{number}/`
+3. Create GitHub deployment with a preview URL
+4. Comment on the PR with the preview link
+
+### Preview URLs
+
+Previews are accessible at:
+- **Demo**: `http://{CDN_IP}/_previews/pr-{number}/` (or `https://storage.googleapis.com/flourish-terreno-terreno-demo/_previews/pr-{number}/` if CDN is not configured)
+- **Example Frontend**: `http://{CDN_IP}/_previews/pr-{number}/` (or `https://storage.googleapis.com/flourish-terreno-terreno-frontend-example/_previews/pr-{number}/`)
+
+### Preview Cleanup
+
+When you close or merge a PR, the `preview-cleanup.yml` workflow automatically:
+- Deletes preview files from both buckets
+- Deactivates GitHub deployments
+
+## Manual Deployment
+
+To deploy manually without GitHub Actions:
+
+``````bash
+# Demo
+cd demo
+bun install
+bun run compile
+bun run export
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' \
+  dist/ gs://flourish-terreno-terreno-demo/
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html gs://flourish-terreno-terreno-demo/index.html
+
+# Invalidate CDN
+gcloud compute url-maps invalidate-cdn-cache terreno-demo-url-map \
+  --path "/*" --async
+
+# Example Frontend
+cd example-frontend
+bun install
+bun run compile
+bun run export
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' \
+  dist/ gs://flourish-terreno-terreno-frontend-example/
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html gs://flourish-terreno-terreno-frontend-example/index.html
+
+# Invalidate CDN
+gcloud compute url-maps invalidate-cdn-cache terreno-frontend-example-url-map \
+  --path "/*" --async
+``````
+
+## Troubleshooting
+
+### Build Fails with "Module not found"
+
+**Problem**: Workspace dependencies not compiled.
+
+**Solution**: Run `bun run compile` in `ui/` and `rtk/` before building the app.
+
+### Preview URL Returns 404
+
+**Problem**: CDN's `notFoundPage` serves root `index.html`, not the preview's.
+
+**Solution**: The deploy workflow uploads "bare" route objects. Check that the workflow completed successfully.
+
+### CDN Shows Stale Content
+
+**Problem**: CDN cache not invalidated.
+
+**Solution**: Run cache invalidation manually:
+``````bash
+gcloud compute url-maps invalidate-cdn-cache URLMAP_NAME --path "/*" --async
+``````
+
+### Permission Denied on gsutil
+
+**Problem**: Service account lacks permissions.
+
+**Solution**: Grant `roles/storage.objectAdmin`:
+``````bash
+gsutil iam ch "serviceAccount:SA_EMAIL:objectAdmin" gs://BUCKET_NAME
+``````
+
+### SPA Routes Return 404 on Refresh
+
+**Problem**: Bucket not configured with `notFoundPage`.
+
+**Solution**: Run the setup script or manually configure:
+``````bash
+gsutil web set -e index.html gs://BUCKET_NAME
+``````
+
+## Next Steps
+
+- [GCP Hosting Architecture](../explanation/gcp-hosting-architecture.md) — Understand the design
+- [Environment Variables Reference](../reference/environment-variables.md) — Configure runtime settings
+- [Set up CI/CD pipelines](../how-to/README.md) — Automate testing and deployment