@terreno/mcp 0.21.0

package/dist/docs/versioned/next/explanation/gcp-hosting-architecture.md

@@ -0,0 +1,319 @@
+# GCP Hosting Architecture
+
+This document explains the architecture and design decisions behind Terreno's Google Cloud Platform hosting setup for static web apps.
+
+## Overview
+
+The Terreno monorepo hosts two static web applications on Google Cloud Storage (GCS) with Cloud CDN:
+
+- **Demo app** (`demo/`) — UI component showcase
+- **Example frontend** (`example-frontend/`) — Full-stack example with API integration
+
+Both apps use the same architecture pattern optimized for single-page applications (SPAs) with client-side routing.
+
+## Architecture Diagram
+
+``````
+┌─────────────────────────────────────────────────────────────┐
+│                        Client Browser                        │
+└───────────────────────────┬─────────────────────────────────┘
+                            │ HTTP Request
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│               Global Forwarding Rule (Static IP)             │
+│              (e.g., 34.120.xxx.xxx)                          │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       HTTP Proxy                             │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         URL Map                              │
+│           (Routes to default backend bucket)                 │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Backend Bucket (CDN-enabled)               │
+│          (e.g., terreno-demo-backend)                        │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    GCS Bucket (Origin)                       │
+│   (e.g., gs://flourish-terreno-terreno-demo)                │
+│                                                              │
+│   ├── index.html                                            │
+│   ├── _expo/                                                │
+│   │   └── static/                                           │
+│   │       ├── js/                                           │
+│   │       ├── css/                                          │
+│   │       └── media/                                        │
+│   └── _previews/                                            │
+│       └── pr-123/                                           │
+│           └── index.html                                    │
+└─────────────────────────────────────────────────────────────┘
+``````
+
+## Components
+
+### 1. GCS Bucket (Origin)
+
+**Purpose**: Store static assets (HTML, JS, CSS, images).
+
+**Configuration**:
+- **Public access**: `allUsers:objectViewer` IAM binding
+- **Static website config**: `notFoundPage=index.html` for SPA routing
+- **No `mainPageSuffix`**: Avoids GCS 301 redirects that break client routing
+
+**Key Feature**: The `notFoundPage` directive serves `index.html` for any 404, enabling client-side routing. When a user visits `/about` directly, GCS returns `index.html`, and the React Router or Expo Router handles the route client-side.
+
+### 2. Backend Bucket (CDN)
+
+**Purpose**: Serve bucket content with Cloud CDN caching.
+
+**Configuration**:
+- **CDN enabled**: Responses are cached at Google edge locations worldwide
+- **Negative caching disabled**: Prevents Cloud CDN from caching 404 responses, which would cause stale 404s for newly-deployed asset hashes
+- **Linked to GCS bucket**: Single bucket per backend
+
+**Performance**: CDN reduces latency by serving cached content from edge locations closest to users.
+
+### 3. URL Map
+
+**Purpose**: Route incoming requests to the backend bucket.
+
+**Configuration**:
+- **Default service**: Points to the backend bucket
+- **Path-based routing**: All paths (`/*`) route to the same backend
+
+**Extensibility**: URL maps support path-based routing (e.g., `/api/*` → backend service, `/*` → frontend), but Terreno uses a single backend per app.
+
+### 4. HTTP Proxy
+
+**Purpose**: Terminate HTTP connections and forward to the URL map.
+
+**Configuration**:
+- **Protocol**: HTTP (can be upgraded to HTTPS with certificates)
+- **Forwarding**: Passes requests to URL map
+
+**HTTPS Support**: To enable HTTPS, create an SSL certificate and attach it to an HTTPS proxy instead.
+
+### 5. Global Forwarding Rule (Static IP)
+
+**Purpose**: Assign a static external IP address to the HTTP proxy.
+
+**Configuration**:
+- **IP address**: Reserved global static IP (e.g., `34.120.xxx.xxx`)
+- **Port**: 80 (HTTP)
+
+**DNS**: Point your domain's A record to this IP for custom domains.
+
+## Design Decisions
+
+### Why Google Cloud Storage over Netlify?
+
+**Pros**:
+- **Cost**: GCS + CDN is cheaper at scale (no bandwidth limits on free tier ending)
+- **Control**: Full control over caching, CDN configuration, and infrastructure
+- **Integration**: Native integration with other GCP services (Cloud Run backend, Cloud Build, etc.)
+- **Flexibility**: URL maps enable complex routing if needed
+
+**Cons**:
+- **Setup complexity**: Requires manual GCP resource provisioning
+- **No built-in forms/functions**: Netlify provides these; GCS does not
+- **DNS management**: Requires separate DNS configuration (Netlify provides DNS)
+
+**Decision**: GCS is better for Terreno because it's a showcase/demo project with minimal dynamic needs, and cost/control outweigh convenience.
+
+### Cache Strategy
+
+| File Type | Cache-Control Header | Rationale |
+|-----------|----------------------|-----------|
+| **Hashed assets** (e.g., `main.abc123.js`) | `public, max-age=31536000, immutable` | Content hash in filename ensures uniqueness; safe to cache forever |
+| **index.html** | `no-cache, no-store, must-revalidate` | Entry point must never be cached to ensure users get the latest app shell |
+
+**Implementation**: Deployment workflows use `gsutil -h` to set headers during upload:
+``````bash
+# Sync hashed assets with long cache
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' dist/ gs://BUCKET/
+
+# Upload index.html with no-cache
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html gs://BUCKET/index.html
+``````
+
+### SPA Routing Implementation
+
+**Challenge**: SPAs use client-side routing (e.g., `/about`, `/profile`), but GCS has no such files.
+
+**Solution**:
+1. **GCS `notFoundPage`**: Configure bucket with `notFoundPage=index.html`
+2. **CDN behavior**: When a request for `/about` results in a 404, GCS serves `index.html`
+3. **Client-side routing**: The app's router (Expo Router, React Router) reads the URL and renders the correct component
+
+**Why not `mainPageSuffix`?**
+- `mainPageSuffix=index.html` causes GCS to 301 redirect `/demo/` → `/demo/index.html`, breaking client routing and creating duplicate URLs.
+- `notFoundPage` returns 200 with `index.html` content, preserving the original URL.
+
+### Preview Deployment Strategy
+
+**Goal**: Deploy PR previews to unique URLs without polluting production.
+
+**Approach**:
+- **Path-based isolation**: Previews deploy to `_previews/pr-{number}/` within the same bucket
+- **Bare route objects**: Upload HTML files as bare objects (no `.html` extension) for SPA routing
+- **Dynamic baseUrl**: Inject `expo.experiments.baseUrl = /_previews/pr-123` during build
+
+**Example**:
+``````
+gs://bucket/
+  ├── index.html                         (production)
+  ├── _expo/static/js/main.abc.js        (production)
+  └── _previews/
+      ├── pr-123                         (bare object, serves preview index.html)
+      └── pr-123/
+          ├── index.html                 (preview root)
+          └── _expo/static/js/main.def.js
+``````
+
+**CDN Limitation**: The CDN's `notFoundPage` always serves the root `index.html`, not the preview's. To work around this:
+1. Upload preview routes as bare objects (e.g., `_previews/pr-123/about` → `about.html` uploaded without extension)
+2. Set `Content-Type: text/html` manually
+
+**Trade-off**: This adds complexity but keeps previews in the same bucket, simplifying cleanup.
+
+## Deployment Flow
+
+### Production Deploy
+
+1. **Trigger**: Push to `master` branch with changes to `demo/**`, `ui/**`, `example-frontend/**`, `rtk/**`
+2. **Build**: GitHub Actions runs `bun run export` to generate static files
+3. **Ensure negative caching disabled**: Update backend bucket to prevent cached 404s
+4. **Upload**:
+   - Sync new hashed assets (additive, no deletions) so old bundles remain available
+   - Upload `index.html` with no-cache header, atomically switching to new bundle hashes
+5. **Invalidate CDN**: `gcloud compute url-maps invalidate-cdn-cache --path "/*"` clears all cached paths
+6. **Cleanup**: Sync with deletions (`-d`) to remove old assets no longer referenced
+
+### Preview Deploy
+
+1. **Trigger**: Open PR with changes to relevant paths
+2. **Build**: Inject `baseUrl` and run `bun run export`
+3. **Upload**:
+   - Upload to `_previews/pr-{number}/`
+   - Create bare route objects for SPA routing
+4. **GitHub Deployment**: Create deployment with preview URL
+5. **Comment**: Bot comments on PR with the preview link
+
+### Preview Cleanup
+
+1. **Trigger**: PR closed or merged
+2. **Delete**: `gsutil -m rm -r gs://BUCKET/_previews/pr-{number}/`
+3. **Deactivate**: Mark GitHub deployments as inactive
+
+## Security Considerations
+
+### Public Read Access
+
+**Risk**: Anyone can access bucket contents.
+
+**Mitigation**: Only public-facing demo apps are hosted. No sensitive data or credentials are stored in GCS.
+
+### Service Account Permissions
+
+**Principle of Least Privilege**: The CI service account has:
+- `roles/storage.objectAdmin` on specific buckets (not project-wide)
+- `roles/compute.loadBalancerAdmin` for CDN cache invalidation only
+
+**Key Storage**: `GCP_SA_KEY` secret is encrypted in GitHub Secrets and never logged.
+
+## Cost Optimization
+
+### Storage Costs
+
+- **GCS Standard**: ~$0.02/GB/month
+- **Typical app size**: ~5-10 MB
+- **Monthly cost**: < $0.01/month per app
+
+### CDN Costs
+
+- **Cache hit**: ~$0.08/GB
+- **Cache miss**: ~$0.12/GB (includes origin fetch)
+- **Expected traffic**: Low (demo/example apps)
+- **Monthly cost**: < $5/month for both apps
+
+### Optimization Strategies
+
+1. **Maximize cache hits**: Long cache headers on hashed assets
+2. **Minimize origin fetches**: CDN caches effectively
+3. **Compress assets**: Expo build automatically gzips/brotlis assets
+4. **Delete old previews**: Cleanup workflow prevents accumulation
+
+## Monitoring and Observability
+
+### Metrics
+
+Monitor via GCP Console:
+- **Storage**: Bucket size, object count
+- **CDN**: Cache hit rate, request count, bandwidth
+- **Costs**: Cloud Billing dashboard
+
+### Alerts
+
+Set up budget alerts in GCP:
+``````bash
+gcloud billing budgets create \
+  --billing-account=BILLING_ACCOUNT_ID \
+  --display-name="Terreno Hosting Budget" \
+  --budget-amount=20USD \
+  --threshold-rule=percent=90
+``````
+
+### Logs
+
+- **Access logs**: Enable bucket access logging if needed
+- **CDN logs**: Enable Cloud CDN logging for request analysis
+
+## Future Improvements
+
+### HTTPS Support
+
+1. Reserve a domain (e.g., `demo.terreno.dev`)
+2. Create an SSL certificate:
+   ``````bash
+   gcloud compute ssl-certificates create terreno-demo-cert \
+     --domains=demo.terreno.dev \
+     --global
+   ``````
+3. Create HTTPS proxy and forwarding rule
+4. Update DNS A record
+
+### Custom Domains
+
+Point DNS A records to the static IPs:
+``````
+demo.terreno.dev.     A     34.120.xxx.xxx
+example.terreno.dev.  A     34.149.xxx.xxx
+``````
+
+### CDN Performance Tuning
+
+- **Geo-routing**: Use Cloud Load Balancing for region-specific backends
+- **Compression**: Enable brotli/gzip at CDN level
+- **Pre-warming**: Warm CDN cache after deployments
+
+### Multi-Region Redundancy
+
+- Replicate buckets to multiple regions
+- Use Cloud Load Balancing to route to nearest region
+
+## Related Documentation
+
+- [Deploy to GCP](../how-to/deploy-to-gcp.md) — Step-by-step deployment guide
+- [Environment Variables Reference](../reference/environment-variables.md) — Configure runtime settings
+- [GCP Documentation: Hosting a Static Website](https://cloud.google.com/storage/docs/hosting-static-website) — Official GCS guide

package/dist/docs/versioned/next/explanation/model-router-actions.md

@@ -0,0 +1,156 @@
+# modelRouter actions
+
+`modelRouter` can register **actions** — named operations at collection or instance scope — alongside standard CRUD. Actions reuse the same permission model, error envelope, and OpenAPI pipeline as CRUD routes, without hand-wiring `endpoints`, `asyncHandler`, and doc loading.
+
+## When to use actions
+
+Use actions when an endpoint performs an operation that is not a plain create/read/update/delete on the model document:
+
+- **Collection scope** (`POST /todos/bulkComplete`) — operate on many documents or the collection as a whole.
+- **Instance scope** (`POST /todos/:id/markComplete`) — operate on one loaded document.
+
+Use [custom routes with `createOpenApiBuilder`](./modular-api-design.md) when the URL does not fit the `/:id/{actionName}` or `/{actionName}` pattern.
+
+## Example
+
+```typescript
+import {modelRouter, Permissions, z} from "@terreno/api";
+import {Todo} from "../models";
+
+export const todoRouter = modelRouter("/todos", Todo, {
+  permissions: {
+    create: [Permissions.IsAuthenticated],
+    list: [Permissions.IsAuthenticated],
+    read: [Permissions.IsOwner],
+    update: [Permissions.IsOwner],
+    delete: [Permissions.IsOwner],
+  },
+  instanceActions: {
+    markComplete: {
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+      handler: async ({doc}) => {
+        doc.completed = true;
+        await doc.save();
+        return doc;
+      },
+      summary: "Mark a todo complete",
+    },
+  },
+  collectionActions: {
+    bulkComplete: {
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      response: z.object({matched: z.number(), modified: z.number()}).strict(),
+      handler: async ({body, user}) => {
+        // updateMany using body.ids and user._id
+      },
+      summary: "Mark multiple todos complete",
+    },
+  },
+});
+```
+
+Use `.strict()` on Zod object schemas when you want unknown JSON keys rejected at runtime. Zod’s default object behavior strips unknown keys.
+
+## Handler context
+
+Handlers receive a single context object:
+
+| Field | Instance | Collection |
+|-------|----------|------------|
+| `req`, `res`, `user` | yes | yes |
+| `doc` | loaded document | — |
+| `body` | parsed body (see below) | parsed body |
+| `query` | parsed query | parsed query |
+
+Return a plain value from the handler; the framework responds with `{data: <value>}` and status `200` (or `action.status` if set). If the handler writes the response itself (`res.json`, streaming), return without relying on auto-wrap — the framework skips wrapping when `res.headersSent` is true.
+
+## Permissions
+
+Each action requires a non-empty `permissions` array (same `PermissionMethod` types as CRUD). An empty array disables the action and returns **405**, matching CRUD.
+
+HTTP method and scope map to a CRUD permission check:
+
+| Scope | GET | POST |
+|-------|-----|------|
+| Instance | `read` | `update` |
+| Collection | `list` | `create` |
+
+**405** — denied before a document is loaded (or on any collection action denial).  
+**403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
+**401** — unauthenticated when a permission requires auth (from existing auth middleware).
+
+`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD.
+
+## Validation
+
+Optional `body` and `query` Zod schemas validate input. On failure the API returns **400** with `title: "Validation failed"` and field errors in `meta.fields`.
+
+Parsed values are passed only through `ctx.body` / `ctx.query`. Express 5 does not allow reassigning `req.query`; do not mutate `req.body` in middleware.
+
+When no `body` or `query` schema is configured, the raw `req.body` / `req.query` are passed through (for manual validation in the handler).
+
+## Document loading (instance actions)
+
+Instance actions load the document by `id` before the handler runs. Missing documents return **404**, including soft-delete metadata when applicable.
+
+`queryFilter` is **not** applied to this load (same as CRUD permission middleware). List filters may hide a document that still exists; post-load permission checks are responsible for access control.
+
+`req.obj` is set to the loaded document for parity with CRUD update/delete handlers.
+
+## OpenAPI and SDK codegen
+
+When `openApi` is configured on the router (automatic with `TerrenoApp` and `setupServer`), each action is documented on first route registration. Operations use:
+
+- **Tag** — model collection name by default; override with `action.tag`.
+- **operationId** — `{tag}_{actionName}` (e.g. `todos_markComplete`) for stable RTK Query hook names after SDK regeneration.
+
+Request/response schemas are derived from Zod when `body`, `query`, or `response` are set. Successful responses are documented as `{data: ...}` to match the wire format.
+
+## Collision detection
+
+At router build time, Terreno rejects:
+
+- Empty action names or names that do not match `/^[A-Za-z][A-Za-z0-9_-]+$/`
+- Instance action names that match a Mongoose array field path (which would collide with `POST /:id/:field` array routes)
+
+Actions are registered before user `endpoints` callbacks, so they take precedence if paths overlap.
+
+## Migrating from `endpoints`
+
+Before (hand-rolled):
+
+```typescript
+endpoints: (router) => {
+  router.post("/generate", [authenticateMiddleware()], asyncHandler(async (req, res) => {
+    // manual admin check, validation, OpenAPI omitted
+    return res.json({data: result});
+  }));
+},
+```
+
+After:
+
+```typescript
+collectionActions: {
+  generate: {
+    method: "POST",
+    permissions: [Permissions.IsAuthenticated],
+    handler: async ({body, user}) => { /* ... */ return result; },
+  },
+},
+```
+
+Remove duplicate `asyncHandler`, `authenticateMiddleware`, and manual `{data: ...}` wrapping unless you need a custom response shape.
+
+## Dependencies
+
+`@terreno/api` lists **`zod` as a peer dependency** (^4.3.x). Applications that define action schemas must install `zod` in the backend project. Import `z` from `@terreno/api` (re-exported after OpenAPI extension) so action Zod schemas work with automatic OpenAPI generation.
+
+`@asteasolutions/zod-to-openapi` is bundled with `@terreno/api` for OpenAPI schema generation.
+
+## Concurrency
+
+Action handlers run the same as other Express handlers — no transactions or locking. Use application-level guards (version fields, idempotency keys) if you need to prevent double-submit races.