@terreno/mcp 57.1.0 → 57.2.0

package/src/docs/versioned/0.27.0/how-to/configure-better-auth.md

@@ -1,296 +0,0 @@
-# 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/src/docs/versioned/0.27.0/how-to/deploy-to-gcp.md

@@ -1,244 +0,0 @@
-# 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