@terreno/mcp 0.21.0 → 0.22.0

package/src/docs/versioned/0.21.0/implementationPlans/upgrade-banner.md

@@ -0,0 +1,275 @@
+# Implementation Plan: Upgrade Banner
+
+*When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
+
+## Models
+
+### VersionConfig (new, singleton)
+
+```typescript
+// api/src/models/versionConfig.ts
+
+import {createdUpdatedPlugin} from "../plugins";
+import mongoose from "mongoose";
+
+const versionConfigSchema = new mongoose.Schema<VersionConfigDocument>(
+  {
+    webWarningVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which web users see a warning toast",
+    },
+    webRequiredVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which web users are blocked from using the app",
+    },
+    mobileWarningVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which mobile users see a warning toast",
+    },
+    mobileRequiredVersion: {
+      type: Number,
+      default: 0,
+      description: "Build number at which mobile users are blocked from using the app",
+    },
+    warningMessage: {
+      type: String,
+      default: "A new version is available. Please update for the best experience.",
+      description: "Message shown in the warning toast",
+    },
+    requiredMessage: {
+      type: String,
+      default: "This version is no longer supported. Please update to continue.",
+      description: "Message shown on the blocking screen",
+    },
+    updateUrl: {
+      type: String,
+      description: "App store or download URL for mobile updates (optional, falls back to expo-updates)",
+    },
+  },
+  { strict: "throw", toJSON: { virtuals: true }, toObject: { virtuals: true } }
+);
+
+versionConfigSchema.plugin(createdUpdatedPlugin);
+```
+
+**Key design points:**
+- Singleton — only one document in the collection
+- All version fields default to `0` (meaning "no constraint"), so the check returns "ok" until an admin configures thresholds
+- Per-platform version thresholds (web vs mobile), shared messages
+- `updateUrl` is optional — mobile falls back to expo-updates OTA
+
+## APIs
+
+### 1. Version Check (public, built-in)
+
+| | |
+|---|---|
+| Method | `GET /version-check` |
+| Auth | None (public) |
+| Query Params | `version` (integer build number), `platform` ("web" \| "mobile") |
+| Response | `{status: "ok" \| "warning" \| "required", message?: string, updateUrl?: string}` |
+| Notes | Requires explicit registration via `VersionCheckPlugin` (e.g., `app.register(new VersionCheckPlugin())`). Returns `{status: "ok"}` if no VersionConfig document exists. |
+
+**Logic:**
+```
+if platform version < requiredVersion → status: "required", message: requiredMessage, updateUrl
+else if platform version < warningVersion → status: "warning", message: warningMessage, updateUrl
+else → status: "ok"
+```
+
+### 2. Admin: Get Version Config
+
+| | |
+|---|---|
+| Method | `GET /admin/version-config` |
+| Auth | `Permissions.IsAdmin` |
+| Response | The singleton VersionConfig document (or defaults if none exists) |
+
+### 3. Admin: Update Version Config
+
+| | |
+|---|---|
+| Method | `PUT /admin/version-config` |
+| Auth | `Permissions.IsAdmin` |
+| Body | All VersionConfig fields |
+| Response | Updated VersionConfig document |
+| Notes | Upsert — creates if doesn't exist, updates if it does. |
+
+Custom routes (not modelRouter) since it's a singleton — no list, no delete, no `:id` params.
+
+## Notifications
+
+No notifications required for this feature. The upgrade system is passive — it checks on app mount and shows in-app UI only.
+
+## UI
+
+### Component 1: `UpgradeRequiredScreen` (new, `@terreno/ui`)
+
+- Full-screen page with centered content
+- Warning icon, the `requiredMessage` text, and an "Update" button
+- Update button behavior controlled by `onUpdate` callback prop:
+  - **Web:** calls `window.location.reload()`
+  - **Mobile:** attempts `expo-updates` OTA → falls back to opening `updateUrl` via `Linking`
+- No back button, no navigation, no dismiss — user is stuck here
+- Props: `message: string`, `onUpdate: () => void`
+
+### Component 2: `useUpgradeCheck` hook (new, `@terreno/rtk`)
+
+- Called in consuming app's root layout
+- On mount: `GET /version-check?version={buildNumber}&platform={web|mobile}`
+- If `"warning"`: shows persistent toast with message + "Update" action button
+- If `"required"`: returns a flag for the consuming app to render `UpgradeRequiredScreen`
+- Returns: `{isRequired: boolean, requiredMessage?: string, onUpdate: () => void}`
+- Skips check if build number is missing/unknown (dev environment)
+- `onUpdate` handles platform logic: web refresh, mobile expo-updates or Linking to updateUrl
+
+### Component 3: Admin Version Config Screen (new, `@terreno/admin-frontend`)
+
+- Form with fields: webWarningVersion, webRequiredVersion, mobileWarningVersion, mobileRequiredVersion, warningMessage, requiredMessage, updateUrl
+- Single "Save" button that PUTs the singleton
+- Accessible from the admin model list as a special entry
+
+### Navigation Flow
+
+```
+App mounts → useUpgradeCheck() fires
+  → "ok"       → normal app
+  → "warning"  → normal app + persistent toast with "Update" button + dismiss X
+  → "required" → UpgradeRequiredScreen (blocks everything)
+```
+
+## Phases
+
+### Phase 1: Backend + Admin
+
+- VersionConfig Mongoose model in `@terreno/api`
+- `GET /version-check` public endpoint via `VersionCheckPlugin`
+- `GET/PUT /admin/version-config` admin routes
+- Admin frontend screen for version config
+- Unit tests for the version check logic
+- Example backend wired up
+
+**Deliverable:** Admin can configure version thresholds and the public endpoint responds correctly.
+
+### Phase 2: Client + CI
+
+- `UpgradeRequiredScreen` component in `@terreno/ui`
+- `useUpgradeCheck` hook in `@terreno/rtk`
+- `app.config.ts` helper for build number injection via `expo.extra.buildNumber`
+- Example frontend wired up with the hook
+- GitHub Actions snippet for `git rev-list --count HEAD`
+
+**Deliverable:** Client apps can check version on mount and show warning toast or blocking screen.
+
+## Feature Flags & Migrations
+
+- **No feature flag needed.** The system is inert by default — the endpoint returns `"ok"` until an admin creates a VersionConfig document with non-zero thresholds.
+- **No data migration needed.** New model, new collection, starts empty.
+- **Rollout:** Ship it. Apps that don't call `useUpgradeCheck()` are unaffected.
+
+## Activity Log & User Updates
+
+No activity logging needed for this feature. Version config changes are admin-only and low-frequency.
+
+## Not Included / Future Work
+
+- Per-user or per-role version targeting
+- Gradual rollout / percentage-based enforcement
+- Push notifications for version updates
+- Automatic semver bumping (stays manual via git tags)
+- Periodic polling (only checks on mount for now)
+- Per-app configs for multi-frontend backends
+- Version check middleware on every API response
+- Analytics on how many users are on which versions
+
+
+# Research: Terreno Upgrade Banner System
+
+## Summary
+
+The Terreno codebase already sends `App-Version` and `App-Platform` headers with every API request via RTK's base query. Building an upgrade banner system requires: (1) a backend model + built-in endpoint for version config, (2) admin screens to manage it, (3) a client hook + prebuilt UI, and (4) CI automation for commit-count-based versioning. The existing `AdminApp` plugin pattern, `Banner` component, toast system, and `Page` component provide strong foundations to build on.
+
+## Context
+
+- **Problem:** No mechanism to notify users their app is outdated. Stale clients can hit deprecated APIs or miss critical fixes.
+- **Current state:** RTK already sends `App-Version` (from `Constants.expoConfig?.version`) and `App-Platform` ("web"/"mobile") on every request (`rtk/src/emptyApi.ts:164-177`). But nothing consumes these headers or enforces version constraints.
+- **Goal:** Two-tier system — soft warning (dismissible toast/banner) and hard block (full-screen, no dismiss). Admin-configurable. Auto-versioned via CI.
+
+## Decisions
+
+- **Per-platform config:** Yes — separate thresholds for web vs mobile since web can force-refresh but mobile needs app store update.
+- **Update mechanism:** Platform-specific — web forces page refresh, mobile triggers expo-updates OTA if available, falls back to app store link.
+- **Endpoint location:** `VersionCheckPlugin` registered with `TerrenoApp` — opt-in per app.
+- **Config storage:** Mongoose model (database-backed) so admins can change without redeploy.
+
+## Findings
+
+### Finding 1: Existing Version Infrastructure in RTK
+
+`rtk/src/emptyApi.ts:164-177` — Every API request already includes:
+```typescript
+const version = Constants.expoConfig?.version ?? "Unknown";
+headers.set("App-Version", version);
+headers.set("App-Platform", IsWeb ? "web" : "mobile");
+```
+
+The version comes from `expo-constants` → `app.json`'s `version` field. Currently `example-frontend/app.json` has `"version": "1.0.0"`.
+
+### Finding 2: Admin Backend Plugin Pattern
+
+`admin-backend/src/adminApp.ts` — The `AdminApp` class provides the pattern:
+- Constructor takes config, `register(app)` adds routes to Express
+- Uses `modelRouter` with `Permissions.IsAdmin` for all CRUD
+- Exposes a `/admin/config` metadata endpoint
+
+### Finding 3: Admin Frontend Patterns
+
+`admin-frontend/` uses a data-driven approach:
+- `useAdminConfig(api, baseUrl)` fetches model metadata
+- `useAdminApi(api, routePath, modelName)` generates CRUD hooks dynamically
+- All screens accept `baseUrl` and `api` props
+- For upgrade config, we need a custom admin screen (singleton config, not a collection)
+
+### Finding 4: UI Components Available
+
+**Banner** (`ui/src/Banner.tsx`) — status variants, persistent dismiss, action button
+**Toast** (`ui/src/Toast.tsx`) — `useToast()` with warn/info/error variants, persistent mode
+**Page** (`ui/src/Page.tsx`) — Full-screen layout for the blocking screen
+**Modal** (`ui/src/Modal.tsx`) — Dialog, but Page is better for hard block (zero escape)
+
+### Finding 5: GitHub Actions & Versioning
+
+Current flow: manual git tag → `publish-on-tag.yml` → selective npm publish.
+No existing build number system. `app.json` version is static.
+`git rev-list --count HEAD` provides simple, monotonically increasing build numbers.
+
+### Finding 6: RTK Store Integration
+
+`example-frontend/store/index.ts` — store combines auth, appState, API reducers.
+`_layout.tsx` checks auth state and routes conditionally — upgrade check follows same pattern.
+
+## Recommendation
+
+**Add to core packages** — spread across:
+- `@terreno/api` — VersionConfig model + public `GET /version-check` endpoint (via `VersionCheckPlugin`)
+- `@terreno/admin-frontend` — Custom admin screen for version config
+- `@terreno/rtk` — `useUpgradeCheck` hook
+- `@terreno/ui` — `UpgradeRequiredScreen` blocking component
+
+**Versioning:** `git rev-list --count HEAD` as integer build number. Helper in CI to set `expo.version` at build time.
+
+**API:** `GET /version-check?version=123&platform=web` — public, no auth. Returns `{status: "ok" | "warning" | "required", message?, updateUrl?}`.
+
+## References
+
+- `rtk/src/emptyApi.ts:164-177` — Existing App-Version header
+- `admin-backend/src/adminApp.ts` — Plugin registration pattern
+- `admin-frontend/src/useAdminApi.tsx` — Dynamic RTK hook generation
+- `ui/src/Banner.tsx` — Banner component
+- `ui/src/Toast.tsx` — Toast notification system
+- `ui/src/Page.tsx` — Full-screen page layout
+- `example-frontend/app/_layout.tsx` — Root layout with auth routing
+- `.github/workflows/publish-on-tag.yml` — Current CI/CD versioning

package/src/docs/versioned/0.21.0/reference/README.md

@@ -0,0 +1,22 @@
+# Reference
+
+Technical reference for Terreno packages and APIs. Information-oriented, precise descriptions.
+
+## Packages
+
+- [@terreno/api](api.md) — modelRouter, auth, permissions, setupServer
+- [@terreno/ui](ui.md) — Components, theming, layout
+- [@terreno/rtk](rtk.md) — Auth slice, SDK codegen, token handling
+- [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
+- [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
+- [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
+- [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
+
+## Configuration
+
+- [Environment Variables](environment-variables.md) — Complete environment variable reference for all packages
+
+## Other references
+
+- Root [package.json](https://github.com/flourishhealth/terreno/blob/master/package.json) — Workspace scripts and catalog
+- Per-package `package.json` in each package directory — Commands and dependencies

package/src/docs/versioned/0.21.0/reference/admin-backend.md

@@ -0,0 +1,122 @@
+# @terreno/admin-backend
+
+Backend plugin that auto-generates admin CRUD endpoints for Mongoose models. Works with `@terreno/admin-frontend` to provide a complete admin panel solution.
+
+## Quick Start
+
+``````typescript
+import {AdminApp} from "@terreno/admin-backend";
+import {User, Todo} from "./models";
+
+const admin = new AdminApp({
+  basePath: "/admin",
+  models: [
+    {
+      model: User,
+      routePath: "/users",
+      displayName: "Users",
+      listFields: ["email", "name", "admin"],
+      defaultSort: "-created",
+    },
+    {
+      model: Todo,
+      routePath: "/todos",
+      displayName: "Todos",
+      listFields: ["title", "completed", "ownerId"],
+    },
+  ],
+});
+
+admin.register(app);
+``````
+
+This creates:
+- `GET /admin/config` — Model metadata endpoint
+- Standard CRUD routes for each model at `{basePath}{routePath}`
+- All routes protected with `Permissions.IsAdmin`
+
+## AdminApp Options
+
+``````typescript
+interface AdminOptions {
+  models: AdminModelConfig[];
+  basePath?: string;  // Default: "/admin"
+}
+
+interface AdminModelConfig {
+  model: Model<any>;
+  routePath: string;      // e.g., "/users"
+  displayName: string;    // e.g., "Users"
+  listFields: string[];   // Fields shown in table
+  defaultSort?: string;   // Default: "-created"
+}
+``````
+
+## Generated Routes
+
+For each model, creates standard modelRouter CRUD endpoints:
+
+- `GET {basePath}{routePath}` — List (paginated, sortable)
+- `POST {basePath}{routePath}` — Create
+- `GET {basePath}{routePath}/:id` — Read
+- `PATCH {basePath}{routePath}/:id` — Update
+- `DELETE {basePath}{routePath}/:id` — Delete
+
+## Config Endpoint
+
+`GET {basePath}/config` returns metadata for all registered models:
+
+``````typescript
+{
+  models: [
+    {
+      name: "User",
+      routePath: "/admin/users",
+      displayName: "Users",
+      listFields: ["email", "name", "admin"],
+      defaultSort: "-created",
+      fields: {
+        email: {
+          type: "string",
+          required: true,
+          description: "User email address"
+        },
+        admin: {
+          type: "boolean",
+          required: false,
+          default: false
+        }
+      }
+    }
+  ]
+}
+``````
+
+Field metadata includes:
+- `type` — Field type (string, number, boolean, date, objectid, etc.)
+- `required` — Whether field is required
+- `description` — From schema (ensure all fields have descriptions!)
+- `enum` — Enum values if applicable
+- `default` — Default value
+- `ref` — Referenced model name for ObjectId refs
+
+## Permissions
+
+All admin routes use `Permissions.IsAdmin`, which checks `user.admin === true`.
+
+**Important:** Only expose models that should be editable via admin panel. Avoid sensitive internal models.
+
+## Best Practices
+
+- Add `description` to all model fields — flows through to admin UI
+- Use `listFields` to control which columns appear in table views
+- Set `defaultSort` to control initial ordering (usually `"-created"`)
+- Keep `routePath` simple and pluralized (`"/users"`, `"/todos"`)
+
+## Integration
+
+Works seamlessly with `@terreno/admin-frontend`. The frontend uses the `/admin/config` endpoint to:
+- Discover available models
+- Generate forms with proper field types
+- Render references as clickable links
+- Validate required fields

package/src/docs/versioned/0.21.0/reference/admin-frontend.md

@@ -0,0 +1,205 @@
+# @terreno/admin-frontend
+
+React Native components for building admin panels that connect to `@terreno/admin-backend`.
+
+## Quick Start
+
+``````typescript
+// app/admin/index.tsx
+import {AdminModelList} from "@terreno/admin-frontend";
+import {api} from "@/store/openApiSdk";
+
+export default function AdminScreen() {
+  return <AdminModelList baseUrl="/admin" api={api} />;
+}
+``````
+
+## Components
+
+### AdminModelList
+
+Entry screen showing all available models as cards.
+
+``````typescript
+<AdminModelList
+  baseUrl="/admin"
+  api={api}
+/>
+``````
+
+Fetches config from `{baseUrl}/config` and displays clickable model cards.
+
+### AdminModelTable
+
+Table view for a specific model with pagination, sorting, and actions.
+
+``````typescript
+<AdminModelTable
+  baseUrl="/admin"
+  api={api}
+  modelName="User"
+/>
+``````
+
+Features:
+- DataTable with columns from backend `listFields`
+- Click row to edit
+- "Create New" button
+- Pagination controls
+- Reference fields render as clickable links
+
+### AdminModelForm
+
+Create or edit form for a model instance.
+
+``````typescript
+<AdminModelForm
+  baseUrl="/admin"
+  api={api}
+  modelName="User"
+  id="507f1f77bcf86cd799439011"  // Optional for edit mode
+/>
+``````
+
+Auto-generates fields from model schema:
+- `string` → TextField
+- `boolean` → BooleanField
+- `number` → NumberField
+- `date` → DateTimeField
+- `objectid` (ref) → SelectField
+- `enum` → SelectField with options
+
+System fields (`_id`, `__v`, `created`, `updated`, `deleted`) are automatically skipped.
+
+### AdminFieldRenderer
+
+Renders field values in table cells with formatting.
+
+``````typescript
+<AdminFieldRenderer
+  value={value}
+  field={fieldConfig}
+  modelName="User"
+  baseUrl="/admin"
+/>
+``````
+
+Handles booleans, dates, ObjectId refs, arrays, objects, and null/undefined.
+
+### AdminRefField
+
+Renders reference fields as clickable links.
+
+``````typescript
+<AdminRefField
+  value={userId}
+  refModel="User"
+  baseUrl="/admin"
+/>
+``````
+
+## Hooks
+
+### useAdminConfig
+
+Fetches admin configuration from backend.
+
+``````typescript
+const {config, isLoading, error} = useAdminConfig(api, baseUrl);
+``````
+
+Returns model metadata from `{baseUrl}/config`.
+
+### useAdminApi
+
+Generates RTK Query hooks for CRUD operations.
+
+``````typescript
+const {
+  useListQuery,
+  useGetQuery,
+  useCreateMutation,
+  useUpdateMutation,
+  useDeleteMutation,
+} = useAdminApi(api, baseUrl, modelName);
+
+const {data, isLoading} = useListQuery({limit: 20, page: 1});
+const [create] = useCreateMutation();
+await create({email: "user@example.com"}).unwrap();
+``````
+
+## Expo Router Setup
+
+``````typescript
+// app/admin/_layout.tsx
+import {Stack} from "expo-router";
+
+export default function AdminLayout() {
+  return <Stack screenOptions={{headerShown: false}} />;
+}
+
+// app/admin/index.tsx - Model list
+import {AdminModelList} from "@terreno/admin-frontend";
+export default () => <AdminModelList baseUrl="/admin" api={api} />;
+
+// app/admin/[modelName]/index.tsx - Model table
+import {AdminModelTable} from "@terreno/admin-frontend";
+export default () => {
+  const {modelName} = useLocalSearchParams();
+  return <AdminModelTable baseUrl="/admin" api={api} modelName={modelName} />;
+};
+
+// app/admin/[modelName]/new.tsx - Create form
+import {AdminModelForm} from "@terreno/admin-frontend";
+export default () => {
+  const {modelName} = useLocalSearchParams();
+  return <AdminModelForm baseUrl="/admin" api={api} modelName={modelName} />;
+};
+
+// app/admin/[modelName]/[id].tsx - Edit form
+import {AdminModelForm} from "@terreno/admin-frontend";
+export default () => {
+  const {modelName, id} = useLocalSearchParams();
+  return <AdminModelForm baseUrl="/admin" api={api} modelName={modelName} id={id} />;
+};
+``````
+
+## Protecting Admin Routes
+
+``````typescript
+// app/_layout.tsx
+import {useSelectCurrentUser} from "@/store/openApiSdk";
+import {Redirect} from "expo-router";
+
+function RootLayout() {
+  const user = useSelectCurrentUser();
+  const pathname = usePathname();
+  
+  if (!user?.admin && pathname.startsWith("/admin")) {
+    return <Redirect href="/" />;
+  }
+  
+  return <Stack />;
+}
+``````
+
+## Custom Field Renderers
+
+Extend `AdminFieldRenderer` for custom field types:
+
+``````typescript
+const CustomFieldRenderer = ({value, field, ...props}) => {
+  if (field.type === "myCustomType") {
+    return <MyCustomComponent value={value} />;
+  }
+  return <AdminFieldRenderer value={value} field={field} {...props} />;
+};
+``````
+
+## Integration
+
+Expects backend to provide:
+1. `GET {baseUrl}/config` — Model metadata
+2. CRUD routes at `{basePath}{routePath}` for each model
+3. Admin authentication (`IsAdmin` permission)
+4. Paginated responses: `{data, page, limit, total, more}`

package/src/docs/versioned/0.21.0/reference/api-health.md

@@ -0,0 +1,81 @@
+# @terreno/api-health
+
+Health check plugin for `@terreno/api` that provides a configurable health endpoint.
+
+## Quick Start
+
+``````typescript
+import {HealthApp} from "@terreno/api-health";
+import {TerrenoApp} from "@terreno/api";
+
+const app = new TerrenoApp({userModel: User})
+  .register(new HealthApp())
+  .start();
+``````
+
+This creates a `GET /health` endpoint that returns `{healthy: true}`.
+
+## Custom Health Checks
+
+Provide a custom check function for more complex health monitoring:
+
+``````typescript
+import {HealthApp} from "@terreno/api-health";
+import mongoose from "mongoose";
+
+const healthApp = new HealthApp({
+  path: "/api/health",
+  check: async () => {
+    try {
+      await mongoose.connection.db.admin().ping();
+      return {
+        healthy: true,
+        details: {database: "connected"},
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        details: {database: "disconnected"},
+      };
+    }
+  },
+});
+
+const app = new TerrenoApp({userModel: User})
+  .register(healthApp)
+  .start();
+``````
+
+## Options
+
+``````typescript
+interface HealthOptions {
+  enabled?: boolean;    // Default: true
+  path?: string;        // Default: "/health"
+  check?: () => Promise<HealthCheckResult> | HealthCheckResult;
+}
+
+interface HealthCheckResult {
+  healthy: boolean;
+  details?: Record<string, any>;
+}
+``````
+
+## Response Codes
+
+- **200** — Service is healthy
+- **503** — Service is unhealthy (when `healthy: false`)
+
+## Use Cases
+
+- **Load balancer health checks** — Simple endpoint for GCP/AWS health monitoring
+- **Database connectivity** — Test connection before accepting requests
+- **Multi-service checks** — Verify external dependencies (Redis, APIs, etc.)
+- **Kubernetes readiness/liveness probes**
+
+## Best Practices
+
+- Keep health checks fast (&lt;1s) — they run frequently
+- Return specific details for debugging: `{database: "connected", cache: "ok"}`
+- Use `/health` for liveness, custom paths for readiness checks
+- Don't expose sensitive information in health check responses