@terreno/mcp 57.2.0 → 57.4.0

package/dist/docs/versioned/0.28.0/implementationPlans/web-ssr-and-admin-spa.md

@@ -1,153 +0,0 @@
-# Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
-
-**Status:** Draft — blocking questions open
-**Priority:** Medium
-**Effort:** Epic
-**Owner:** unassigned
-**Created:** 2026-07-27
-**Program:** [OSS launch](oss-launch-program.md) (Wave 2)
-**Depends on:** Expo SDK ≥ 55 (PR [#779](https://github.com/flourishhealth/terreno/pull/779) upgrades to SDK 56), [`deployment-foundation`](deployment-foundation.md)
-**RTK deprecation flag:** **Partial** — SSR interacts directly with the data layer. Server-rendered HTML needs data at render time, which is a fundamentally different question for a local-first client than for a request/response client. The data-loading design tasks are `[RTK]` marked and blocked on #869.
-
-## Goal
-
-Give Terreno's web target real server rendering, so a Terreno app can be indexed, shared with usable link previews, and load meaningful first paint without waiting for a JavaScript bundle. Then evaluate moving `@terreno/admin-spa` onto the same mechanism, since it is already served from Express and is the lowest-risk consumer.
-
-The Django/Rails positioning makes this gap conspicuous: both frameworks server-render by default. Today Terreno's web output is `single` — a client-only SPA with one `index.html`, no per-route HTML, and no server rendering. For a framework claiming Django/Rails parity plus universal apps, "your web app is not indexable" is a real objection.
-
-## Non-Goals
-
-- Server-rendering native. SSR is web-only by definition.
-- Replacing `@terreno/api` with Expo Router API routes. The backend stays the backend.
-- React Server Components.
-- Making SSR mandatory. It must be opt-in per app.
-- Upgrading the Expo SDK (PR #779 owns that; this IP depends on it).
-
-## Blocking questions
-
-**Recorded 2026-07-29** (defaults accepted).
-
-| # | Decision |
-|---|----------|
-| S1 | **`static` first, `server` later** (SSR alpha in Expo SDK 55+) |
-| S2 | **`expo-server/adapter/express`** in `@terreno/api` as Terreno-native path; document per-provider adapters |
-| S3 | **Shell-only SSR v1** — hydrate on client |
-| S4 | **`admin-spa` moves to `static` output only** |
-| S5 | **`static` becomes default eventually** (after component audit); `server` opt-in |
-| S6 | **Expo Router API routes narrowly** for OG images / webhooks only |
-
-## Architecture
-
-### Where SSR fits
-
-```mermaid
-flowchart TD
-  U["Browser request"]
-  E["Express app (@terreno/api)"]
-  SSR["expo-server/adapter/express<br/>renders dist/server"]
-  C["dist/client<br/>static assets"]
-  API["modelRouter + auth routes"]
-  ADM["AdminSpaServeApp"]
-  U --> E
-  E -->|"/api/*, /auth/*"| API
-  E -->|"/admin/*"| ADM
-  E -->|"static assets"| C
-  E -->|"everything else"| SSR
-  SSR -->|"HTML"| U
-```
-
-One Express process serves the API, the static client bundle, and server-rendered HTML. Route precedence matters: API and auth routes must match before the SSR catch-all, and the admin mount must not be shadowed.
-
-### Risks specific to React Native Web SSR
-
-This is where the work actually is, and where the estimate could be badly wrong:
-
-| Risk | Detail | Mitigation |
-|------|--------|------------|
-| Components that touch browser APIs at module scope | `@terreno/ui` has ~100 components; any that read `window`, `localStorage`, or `Dimensions` during render or module init will throw during server rendering | Audit and fix; the repo already has SSR-safety precedent (`typeof window` checks in the client storage layer) |
-| Fonts and styles | Nunito/Titillium Web loading and `react-native-web` style injection must produce correct first paint without a flash of unstyled content | Verify style extraction; may need explicit critical-CSS handling |
-| Theme and provider hydration | `TerrenoProvider` computes a theme; server and client must agree or React logs hydration mismatches | Ensure deterministic theme resolution; no `Date.now()` or random values in the render path |
-| Auth-dependent rendering | The server does not know who the user is without reading a session; rendering a logged-in shell then hydrating to logged-out causes visible flicker | v1: always render the unauthenticated shell (S3 option A) |
-| Native-only dependencies | Packages that import native modules at the top level break the server bundle | Audit; use platform-specific extensions |
-| Local-first client on the server | The syncdb client assumes IndexedDB and Web Crypto, neither of which exists on the server | The client must not initialize during server render; needs an explicit guard verified after #869 |
-
-The last row is the one that could invalidate the plan, and it cannot be assessed until #869 merges. **Phase 0 exists to answer it before committing to the rest.**
-
-### `admin-spa` as the proving ground
-
-`@terreno/admin-spa` is an Expo Router web app already served from Express via `AdminSpaServeApp`. Moving it to `static` output is a contained experiment: no SEO requirement, one known consumer (`example-backend`), an existing integration test workflow (`admin-spa-integration.yml`), and an authenticated surface where the auth-flicker problem is bounded. If `static` output works there, the pattern generalizes.
-
-## Models / APIs
-
-No new models. `AdminSpaServeApp` gains options for the output mode and the server bundle path. Route precedence in `TerrenoApp`/`setupServer` may need an explicit ordering guarantee so the SSR catch-all cannot shadow API routes.
-
-## Notifications
-
-None.
-
-## UI
-
-No new components. Existing `@terreno/ui` components may need SSR-safety fixes — those are bug fixes, not features, and each needs a test that renders the component in a server-like environment without `window`.
-
-## Phases
-
-0. **Feasibility spike** — after SDK ≥ 55 and #869, attempt `static` output on `example-frontend` and record every failure. Decide go/no-go and correct this plan. **Do not proceed without this.**
-1. **SSR-safety audit and fixes** — make `@terreno/ui` render without browser globals; add a server-render test harness.
-2. **`static` output for `admin-spa`** — prove the pattern on the contained consumer.
-3. **`static` output for `example-frontend`** — the reference implementation plus documentation.
-4. **`server` output with the Express adapter** — SSR through `@terreno/api`, route precedence, deployment implications.
-5. **Data loading design** — a separate design pass on `useLoaderData` versus local-first reconciliation. May become its own IP.
-6. **Documentation and defaults** — how-to, explainer, and the decision on whether `static` becomes the default.
-
-## Feature Flags & Migrations
-
-- Output mode is per-app configuration in the Expo app config, not a runtime flag.
-- `AdminSpaServeApp` must keep serving existing `single`-output builds so consumers upgrading Terreno without changing their admin build are unaffected.
-- Changing the recommended default (S5) is a breaking change for consumers who copied the bootstrap config; it needs an upgrade note.
-
-## Not Included / Future Work
-
-- React Server Components.
-- Streaming SSR.
-- Incremental static regeneration.
-- Server-rendering authenticated, personalized content (depends on Phase 5).
-- Edge-runtime adapters (`workerd`, Netlify Edge) — the adapters exist upstream; document them once the Express path is proven.
-
-## Files to Create / Modify
-
-**Create**
-
-- `docs/how-to/enable-web-ssr.md`
-- `docs/explanation/web-rendering-modes.md`
-- `ui/src/__tests__/serverRender.test.tsx` (server-render harness)
-- `admin-spa/app.config.ts` changes plus a server entry if `server` output is adopted
-
-**Modify**
-
-- `example-frontend/app.json` (output mode)
-- `admin-spa/app.json` / `app.config.ts`
-- `admin-spa/src/**` (SSR-unsafe code)
-- `ui/src/**` (SSR-safety fixes)
-- `api/src/adminSpaServeApp.ts` (or wherever `AdminSpaServeApp` lives — confirm the path) for output-mode support
-- `api/src/expressServer.ts` / `terrenoApp.ts` (route precedence)
-- `docs/explanation/deployment-baseline.md` (update the output-mode table)
-- `.github/workflows/admin-spa-integration.yml`
-
-## Task List
-
-See [`docs/tasks/web-ssr-and-admin-spa.md`](../tasks/web-ssr-and-admin-spa.md).
-
-## Acceptance Criteria
-
-- [ ] The Phase 0 spike produced a written feasibility report listing every failure encountered with `static` output, and an explicit go/no-go with this plan corrected accordingly.
-- [ ] Every `@terreno/ui` component renders in a server-like environment without `window`, `document`, or `localStorage`, verified by an automated test.
-- [ ] `admin-spa` builds and serves correctly with `static` output through `AdminSpaServeApp`, and `admin-spa-integration.yml` passes.
-- [ ] `AdminSpaServeApp` still serves an existing `single`-output build unchanged.
-- [ ] `example-frontend` builds with `static` output, produces per-route HTML, and every route returns HTML containing meaningful content (verified by fetching a route with JavaScript disabled).
-- [ ] No React hydration mismatch warnings in the console on any `example-frontend` route.
-- [ ] If Phase 4 proceeds: `server` output renders through the Express adapter inside `@terreno/api`, API and auth routes take precedence over the SSR catch-all (verified by tests), and the admin mount is not shadowed.
-- [ ] The syncdb client does not attempt to initialize during server render, verified by a test.
-- [ ] `docs/explanation/web-rendering-modes.md` explains all modes with honest tradeoffs and states which Terreno supports.
-- [ ] `docs/how-to/enable-web-ssr.md` takes a reader from `single` to their chosen mode, including the deployment change required.
-- [ ] Deployment guides for both Vercel and GCP are updated for whichever modes ship.
-- [ ] `bun run lint`, `bun run compile`, `bun run ui:test`, and `bun run admin-spa:test` all pass.

package/dist/docs/versioned/0.28.0/reference/README.md

@@ -1,22 +0,0 @@
-# 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/dist/docs/versioned/0.28.0/reference/admin-backend.md

@@ -1,122 +0,0 @@
-# @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/dist/docs/versioned/0.28.0/reference/admin-frontend.md

@@ -1,205 +0,0 @@
-# @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}`