@terreno/mcp 0.31.0 → 56.0.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terreno/mcp",
-  "version": "0.31.0",
+  "version": "56.0.0-beta.0",
   "description": "MCP server for Terreno - provides documentation, tools, and prompts for building full-stack apps",
   "type": "module",
   "main": "dist/index.js",
@@ -27,18 +27,17 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "0.31.0",
+    "@terreno/api": "56.0.0-beta.0",
     "minisearch": "^7.2.0",
-    "mongoose": "9.7.4"
+    "mongoose": "8.23.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
     "@types/bun": "^1.3.8",
     "@types/node": "^25.3.0",
-    "typescript": "~5.9.2"
+    "typescript": "~6.0.3"
   },
   "files": [
-    "LICENSE",
     "dist",
     "src/docs"
   ],

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

@@ -1,17 +1,16 @@
+/// <reference types="passport-local-mongoose" />
 import type {APIErrorConstructor} from "@terreno/api";
 import type mongoose from "mongoose";
-import type {Document, Model} from "mongoose";
-
-type ModelQuery<T> = Partial<Record<keyof T, unknown>> & Record<string, unknown>;
+import type {Document, FilterQuery, Model} from "mongoose";
 
 export interface DefaultStatics<T> {
   findOneOrNone(
-    query: ModelQuery<T>,
+    query: FilterQuery<T>,
     errorArgs?: Partial<APIErrorConstructor>
   ): Promise<(Document & T) | null>;
 
   findExactlyOne(
-    query: ModelQuery<T>,
+    query: FilterQuery<T>,
     errorArgs?: Partial<APIErrorConstructor>
   ): Promise<Document & T>;
 }

package/src/docs/templates/bootstrap/frontend/app/_layout.template.tsx

@@ -1,5 +1,5 @@
 import FontAwesome from "@expo/vector-icons/FontAwesome";
-import {DarkTheme, DefaultTheme, ThemeProvider} from "@react-navigation/native";
+import {DarkTheme, DefaultTheme, ThemeProvider} from "expo-router/react-navigation";
 import {useFonts} from "expo-font";
 import {Stack} from "expo-router";
 import * as SplashScreen from "expo-splash-screen";

package/src/docs/templates/tools/model.template.md

@@ -5,11 +5,9 @@ interface {{Name}}Document extends mongoose.Document {
 {{interfaceFields}}
 }
 
-type ModelQuery<T> = Partial<Record<keyof T, unknown>> & Record<string, unknown>;
-
 interface {{Name}}Model extends mongoose.Model<{{Name}}Document> {
-  findOneOrNone(query: ModelQuery<{{Name}}Document>): Promise<{{Name}}Document | null>;
-  findExactlyOne(query: ModelQuery<{{Name}}Document>): Promise<{{Name}}Document>;
+  findOneOrNone(query: mongoose.FilterQuery<{{Name}}Document>): Promise<{{Name}}Document | null>;
+  findExactlyOne(query: mongoose.FilterQuery<{{Name}}Document>): Promise<{{Name}}Document>;
 }
 
 const {{lowerName}}Schema = new mongoose.Schema<{{Name}}Document, {{Name}}Model>(

package/src/docs/versioned/next/README.md

@@ -17,6 +17,7 @@ Documentation for the Terreno monorepo: shared packages for full-stack applicati
 | [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
 | [@terreno/ui](reference/ui.md) | React Native UI component library |
 | [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
+| [@terreno/syncdb](reference/syncdb.md) | Local-first data layer (offline sync, conflicts) |
 | [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
 | [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
 | [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |

package/src/docs/versioned/next/explanation/README.md

@@ -2,19 +2,13 @@
 
 Understanding-oriented documentation: concepts, architecture, and context.
 
-## Deployment
-
-- [Deployment baseline](deployment-baseline.md) — seven requirements for production Terreno apps
-- [GCP deployment architecture](deployment-architecture-gcp.md) — Cloud Run + GCS/CDN topology and tradeoffs
-- [GCP hosting architecture](gcp-hosting-architecture.md) — static site hosting with GCS and Cloud CDN (legacy detail)
-
 ## Contents
 
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
 - [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
 - [Configuration system](configuration-system.md) — Runtime configuration with database persistence
 - [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
+- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
 - [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
 - [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter
 - [No barrel imports](no-barrel-imports.md) — Import concrete modules, not `index` re-export barrels
-- [Positioning](positioning.md) — Canonical copy blocks and the honest Django/Rails comparison

package/src/docs/versioned/next/how-to/README.md

@@ -2,14 +2,6 @@
 
 Problem-oriented, practical steps. Use these when you know what you want to do.
 
-## Deployment
-
-- [Deployment baseline](../explanation/deployment-baseline.md) — seven requirements every host must satisfy
-- [Build for web](build-for-web.md) — export static web bundle with correct API URL
-- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — index for GCP guides
-- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) — container + Secret Manager + Cloud Run
-- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) — static hosting with SPA routing
-
 ## Contents
 
 - [Create a Mongoose model](create-a-model.md) — Define models with proper conventions
@@ -17,6 +9,8 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Configure Better Auth](configure-better-auth.md) — Set up Better Auth with social OAuth (Google, GitHub, Apple)
 - [Add WebSocket integration](websocket-integration.md) — Set up real-time Socket.io connections
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations
+- [Deploy to Google Cloud Platform](deploy-to-gcp.md) — Deploy demo and example apps to GCS with CDN
+- [Migrate from @terreno/rtk to @terreno/syncdb](migrate-rtk-to-syncdb.md) — Move data sync to the local-first layer
 
 ## Coming Soon
 

package/src/docs/versioned/next/how-to/deploy-to-gcp.md

@@ -1,36 +1,244 @@
 # Deploy to Google Cloud Platform
 
-Deploy a Terreno full-stack app to GCP: Cloud Run for the backend, GCS + Cloud CDN for the static web export.
+Learn how to deploy the Terreno demo and example-frontend apps to Google Cloud Storage with CDN-backed hosting.
 
-## Before you start
+## Prerequisites
 
-Read the [deployment baseline](../explanation/deployment-baseline.md) — seven requirements (replica-set MongoDB, auth secrets, build-time `EXPO_PUBLIC_API_URL`, and more) apply to every provider.
+Before you begin, ensure you have:
 
-## Guides
+- **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
 
-| Guide | What it covers |
-|-------|----------------|
-| [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) | Container image, Secret Manager, Cloud Run with session affinity |
-| [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) | Static web export, bucket + CDN setup, cache invalidation |
-| [Build for web](build-for-web.md) | Export command, `EXPO_PUBLIC_API_URL`, local verification |
+## Initial Infrastructure Setup
 
-## Architecture
+Run the setup script once to provision all GCP resources:
 
-[GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
+``````bash
+# Clone the repository
+git clone https://github.com/FlourishHealth/terreno.git
+cd terreno
 
-## Scripts
+# Run the setup script
+./scripts/setup-gcs-hosting.sh
+``````
 
-- [`scripts/setup-gcs-hosting.sh`](https://github.com/FlourishHealth/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
+The script will prompt you for your service account email if `GCP_SA_KEY` is not set. It will create:
 
-## Environment variables
+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
 
-[Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
+### Script Output
 
-## Legacy Flourish deployment
+At the end, the script outputs:
 
-Flourish-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives in `infra/flourish/` and the existing `demo-deploy.yml` / `frontend-example-deploy.yml` workflows. New deployments should follow the generalized guides above with your own `$PROJECT_ID` and bucket names.
+``````
+=== Setup Complete ===
 
-## Related
+Demo:
+  CDN IP: 34.120.xxx.xxx
+  URL: http://34.120.xxx.xxx/
+  (Point your DNS A record to this IP)
 
-- [Environment variables](../reference/environment-variables.md)
-- [Deployment baseline](../explanation/deployment-baseline.md)
+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