@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/0.30.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/TerrenoLabs/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

package/src/docs/versioned/0.30.0/how-to/upgrade-banner.md

@@ -1,172 +0,0 @@
-# Upgrade Banner
-
-Two-tier system for notifying users about app updates: a soft warning (dismissible toast) and a hard block (full-screen, no dismiss). Admin-configurable thresholds per platform.
-
-## How It Works
-
-1. **Backend** exposes `GET /version-check?version=N&platform=web|mobile` (public, no auth)
-2. **Admin** configures version thresholds via the admin panel
-3. **Client** calls `useUpgradeCheck()` on mount, which compares the app's build number against the thresholds
-4. Result: `ok` (no action), `warning` (persistent toast), or `required` (blocking screen)
-
-## Setup
-
-### 1. Backend: Register the VersionCheckPlugin
-
-```typescript
-import {TerrenoApp, VersionCheckPlugin} from "@terreno/api";
-
-const app = new TerrenoApp({userModel: User})
-  .register(new VersionCheckPlugin())
-  .start();
-```
-
-This adds the public `GET /version-check` endpoint. The admin routes (`GET/PUT /admin/version-config`) are automatically available if you're using `AdminApp`.
-
-### 2. Frontend: Add build number injection
-
-Create or update `app.config.ts` in your Expo app root. Use the `resolveBuildNumber` helper from `@terreno/rtk/buildNumber`:
-
-```typescript
-import {resolveBuildNumber} from "@terreno/rtk/buildNumber";
-import type {ConfigContext, ExpoConfig} from "expo/config";
-
-export default ({config}: ConfigContext): ExpoConfig => ({
-  ...config,
-  extra: {
-    ...config.extra,
-    buildNumber: resolveBuildNumber({configValue: config.extra?.buildNumber}),
-  },
-} as ExpoConfig);
-```
-
-`resolveBuildNumber` resolves the build number in this order:
-
-1. **`override`** option (set to a number for local testing)
-2. **`configValue`** option (e.g. from `app.json` `expo.extra.buildNumber` or EAS Build)
-3. **`EXPO_PUBLIC_BUILD_NUMBER`** env var (customizable via `envVar` option)
-4. **`git rev-list --count HEAD`** (default)
-5. **`undefined`** if git is unavailable (version check will be skipped)
-
-This sets `Constants.expoConfig.extra.buildNumber` when Metro loads the config. By default it tracks the git commit count.
-
-**If you change `buildNumber` and nothing updates:** restart the dev server (`bun expo start` or `expo start --clear`). `expo-constants` is filled when the bundle is built; hot reload does not always re-read `app.config.ts`.
-
-### 3. Frontend: Wire up the hook
-
-In your root layout:
-
-```typescript
-import {useUpgradeCheck} from "@terreno/rtk";
-import {UpgradeRequiredScreen} from "@terreno/ui";
-
-function RootLayoutNav() {
-  const {isRequired, requiredMessage, onUpdate} = useUpgradeCheck();
-
-  if (isRequired) {
-    return (
-      <UpgradeRequiredScreen
-        message={requiredMessage ?? "Please update to continue."}
-        onUpdate={onUpdate}
-      />
-    );
-  }
-
-  return <Stack>{/* normal routes */}</Stack>;
-}
-```
-
-The hook handles:
-- **ok**: Nothing happens, app runs normally
-- **warning**: Shows a persistent toast with the admin-configured message
-- **required**: Returns `isRequired: true` so you can render the blocking screen
-- **No build number**: Skips the check entirely (dev environment)
-
-### 4. Admin: Configure thresholds
-
-Navigate to the admin panel and select "Version Config". Set:
-
-- **Web Warning Version**: Build number below which web users see a warning toast
-- **Web Required Version**: Build number below which web users are blocked
-- **Mobile Warning Version**: Same for mobile
-- **Mobile Required Version**: Same for mobile
-- **Warning Message**: Text shown in the toast
-- **Required Message**: Text shown on the blocking screen
-- **Update URL** (optional): App store or download link for mobile updates
-
-All version fields default to `0`, meaning no constraint until configured.
-
-## CI/CD: Build Number in GitHub Actions
-
-### EAS Build
-
-In your `eas.json`, use a pre-build hook or set the build number via environment:
-
-```yaml
-# .github/workflows/build.yml
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # Required for git rev-list --count
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Build with EAS
-        run: eas build --platform all --non-interactive
-```
-
-Since `app.config.ts` runs `git rev-list --count HEAD` at build time, the build number is automatically set. The key requirement is `fetch-depth: 0` in the checkout step to ensure the full git history is available.
-
-### Web Deployments
-
-For static web builds (e.g. `expo export`):
-
-```yaml
-jobs:
-  deploy-web:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Export web build
-        run: npx expo export --platform web
-
-      - name: Deploy
-        run: # your deployment step
-```
-
-The `app.config.ts` runs during `expo export`, so the build number is embedded in the static output.
-
-### Verifying the Build Number
-
-After building, you can verify the build number is set correctly:
-
-```bash
-# Check the current commit count locally
-git rev-list --count HEAD
-```
-
-This number should match what `Constants.expoConfig.extra.buildNumber` returns in the running app.
-
-## Architecture
-
-```
-App mounts → useUpgradeCheck() fires
-  → GET /version-check?version=N&platform=web|mobile
-  → "ok"       → normal app
-  → "warning"  → normal app + persistent toast
-  → "required" → UpgradeRequiredScreen (blocks everything)
-```
-
-Update behavior when user taps "Update":
-- **Web**: `window.location.reload()` — picks up the latest deployment
-- **Mobile**: Opens `updateUrl` via `Linking.openURL()` (e.g. App Store link)